@cursor/july 0.1.101 → 0.1.103

package/src/internal/discovery/channels.ts

@@ -0,0 +1,105 @@
+/**
+ * `agent/channels/*.ts`: HTTP surfaces beyond the session API.
+ */
+
+import { join } from "node:path";
+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 { validateName } from "./names.js";
+
+export async function loadChannels(
+  ctx: DiscoveryContext,
+  channelsDir: string,
+  mode: "agent" | "extension" = "agent",
+  onDisable?: (id: string, path: string) => void
+): 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 (!validateName(ctx, "channel", id, entryPath)) {
+      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 === "disabled") {
+      onDisable?.(id, entryPath);
+      continue;
+    }
+
+    if (kind === "http-channel") {
+      if (mode === "extension" || id !== "http") {
+        ctx.diagnostics.push({
+          severity: "error",
+          path: displayPath(ctx, entryPath),
+          message:
+            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;
+      }
+      httpChannelDefinition = mod.default as HttpChannelDefinition;
+      continue;
+    }
+
+    if (kind !== "channel") {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, entryPath),
+        message:
+          id === "http" && mode === "agent"
+            ? "channels/http.ts must default-export httpChannel({ ... })."
+            : "Channel modules must default-export defineChannel({ ... }).",
+      });
+      continue;
+    }
+    if (id === "http" && mode === "agent") {
+      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 };
+}

package/src/internal/discovery/connections.ts

@@ -0,0 +1,545 @@
+/**
+ * `agent/mcp-connections/*.ts` and `agent/host-connections/*.ts`: MCP servers for the model and the host.
+ */
+
+import { join } from "node:path";
+import {
+  type ConnectionDefinition,
+  type ConnectionTransport,
+  cursorAccountServersHasMixedWildcard,
+  type DiscoveredConnection,
+  type InlineStdioConnectionConfig,
+  isInlineStdioConnection,
+  isToolEffect,
+  normalizeConnectionEffects,
+  normalizeConnectionTools,
+  normalizeCursorAccountServers,
+  type ToolEffect,
+} from "../../types.js";
+import { packageInlineStdioConnection } from "../package-inline-stdio.js";
+import {
+  type DiscoveryContext,
+  displayPath,
+  errorMessage,
+  isBlank,
+} from "./context.js";
+import { importDefault, moduleEntries } from "./modules.js";
+import { NAME_PATTERN } from "./names.js";
+
+/** One-line `/v1/info` label for a connection transport. */
+export function connectionTransportLabel(
+  transport: ConnectionTransport
+): string {
+  if ("cursorAccount" in transport) {
+    return transport.servers === undefined
+      ? "cursor-account"
+      : `cursor-account:${transport.servers.join(",")}`;
+  }
+  if ("agent" in transport) {
+    return `agent:${transport.agent}`;
+  }
+  if ("url" in transport) {
+    return transport.oauth === true
+      ? `${transport.url} (oauth)`
+      : transport.url;
+  }
+  return transport.command;
+}
+
+function hasAuthorizationHeader(
+  headers: Record<string, string> | undefined
+): boolean {
+  if (headers === undefined) {
+    return false;
+  }
+  return Object.keys(headers).some(
+    (key) => key.toLowerCase() === "authorization"
+  );
+}
+
+function parseConnectionEffects(
+  effects: unknown
+): { ok: true; value: ToolEffect[] | undefined } | { ok: false } {
+  if (effects === undefined) {
+    return { ok: true, value: undefined };
+  }
+  const raw = typeof effects === "string" ? [effects] : effects;
+  if (!Array.isArray(raw) || raw.length === 0) {
+    return { ok: false };
+  }
+  const parsed: ToolEffect[] = [];
+  for (const value of raw) {
+    if (!isToolEffect(value)) {
+      return { ok: false };
+    }
+    parsed.push(value);
+  }
+  return { ok: true, value: normalizeConnectionEffects(parsed) };
+}
+
+function parseConnectionTools(
+  tools: unknown
+): { ok: true; value: string[] | undefined } | { ok: false } {
+  if (tools === undefined) {
+    return { ok: true, value: undefined };
+  }
+  if (!Array.isArray(tools) || tools.length === 0) {
+    return { ok: false };
+  }
+  if (tools.some((name) => typeof name !== "string")) {
+    return { ok: false };
+  }
+  const normalized = normalizeConnectionTools(tools);
+  if (normalized.length === 0) {
+    return { ok: false };
+  }
+  return { ok: true, value: normalized };
+}
+
+function connectionHasSpawnOrRemote(connection: ConnectionDefinition): boolean {
+  if ("cursorAccount" in connection && connection.cursorAccount === true) {
+    return true;
+  }
+  if ("agent" in connection && !isBlank(connection.agent)) {
+    return true;
+  }
+  if ("url" in connection && !isBlank(connection.url)) {
+    return true;
+  }
+  return "command" in connection && !isBlank(connection.command);
+}
+
+function connectionTransport(
+  connection: ConnectionDefinition
+): ConnectionTransport | undefined {
+  if ("cursorAccount" in connection && connection.cursorAccount === true) {
+    const servers = normalizeCursorAccountServers(connection.servers);
+    return {
+      cursorAccount: true,
+      ...(servers === undefined ? {} : { servers }),
+    };
+  }
+  if ("agent" in connection && !isBlank(connection.agent)) {
+    return { agent: connection.agent };
+  }
+  if ("url" in connection && !isBlank(connection.url)) {
+    return {
+      type: connection.type,
+      url: connection.url,
+      headers: connection.headers,
+      oauth: connection.oauth === true ? true : undefined,
+    };
+  }
+  if ("command" in connection && !isBlank(connection.command)) {
+    return {
+      ...(connection.type === undefined ? {} : { type: connection.type }),
+      command: connection.command,
+      ...(connection.args === undefined ? {} : { args: connection.args }),
+      ...(connection.env === undefined ? {} : { env: connection.env }),
+      ...(connection.cwd === undefined ? {} : { cwd: connection.cwd }),
+    };
+  }
+  return undefined;
+}
+
+export async function loadHostConnections(
+  ctx: DiscoveryContext,
+  agentDir: string,
+  modelConnections: readonly DiscoveredConnection[]
+): Promise<DiscoveredConnection[]> {
+  const hostDir = join(agentDir, "host-connections");
+  const loaded = await loadConnections(ctx, hostDir, "host");
+  const modelNames = new Set(
+    modelConnections.map((connection) => connection.name)
+  );
+  const hostConnections: DiscoveredConnection[] = [];
+  for (const connection of loaded) {
+    if (modelNames.has(connection.name)) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, join(hostDir, `${connection.name}.ts`)),
+        message: `Host connection "${connection.name}" collides with agent/mcp-connections/${connection.name}. Rename one of them.`,
+      });
+      continue;
+    }
+    if (
+      rejectHostConnectionFeatures(
+        ctx,
+        join(hostDir, `${connection.name}.ts`),
+        connection
+      )
+    ) {
+      continue;
+    }
+    hostConnections.push(connection);
+  }
+  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,
+  role: "model" | "host" = "model"
+): Promise<DiscoveredConnection[]> {
+  const connections: DiscoveredConnection[] = [];
+  for (const { name, path } of await moduleEntries(
+    ctx,
+    connectionsDir,
+    "connection"
+  )) {
+    const definition = await importDefault(ctx, path, "connection");
+    if (definition === undefined) {
+      continue;
+    }
+    const connection = await compileConnection(
+      ctx,
+      path,
+      name,
+      definition as ConnectionDefinition,
+      role
+    );
+    if (connection !== undefined) {
+      connections.push(connection);
+    }
+  }
+  return connections;
+}
+
+/** Validate one `defineConnection` and resolve its transport. */
+export async function compileConnection(
+  ctx: DiscoveryContext,
+  entryPath: string,
+  name: string,
+  connection: ConnectionDefinition,
+  role: "model" | "host"
+): Promise<DiscoveredConnection | undefined> {
+  if (Object.hasOwn(connection, "hostOnly")) {
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, entryPath),
+      message:
+        "MCP connection `hostOnly` was removed. Files under `agent/mcp-connections/` are always visible to the model. Put privileged servers in `agent/host-connections/` so only host tools can call them.",
+    });
+    return undefined;
+  }
+  if (
+    isInlineStdioConnection(connection) &&
+    connectionHasSpawnOrRemote(connection)
+  ) {
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, entryPath),
+      message:
+        "MCP connection `tools` cannot be combined with `command`, `url`, `agent`, or `cursorAccount`. Author TypeScript tools, or point at an existing server, not both.",
+    });
+    return undefined;
+  }
+  if (connection.auth !== undefined && typeof connection.auth !== "function") {
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, entryPath),
+      message:
+        "MCP connection `auth` must be a function: (session) => { headers }.",
+    });
+    return undefined;
+  }
+  if (connection.auth !== undefined && !("url" in connection)) {
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, entryPath),
+      message:
+        "MCP connection `auth` (per-session headers) is only supported on http/sse connections (`url`).",
+    });
+    return undefined;
+  }
+  if (
+    connection.advertiseTools !== undefined &&
+    typeof connection.advertiseTools !== "boolean"
+  ) {
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, entryPath),
+      message: "MCP connection `advertiseTools` must be a boolean.",
+    });
+    return undefined;
+  }
+  const parsedEffects = parseConnectionEffects(connection.effects);
+  if (!parsedEffects.ok) {
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, entryPath),
+      message:
+        'MCP connection `effects` must be "read", "write", or a non-empty array of those.',
+    });
+    return undefined;
+  }
+  if (parsedEffects.value !== undefined && connection.advertiseTools !== true) {
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, entryPath),
+      message:
+        "MCP connection `effects` filters advertised tools; set `advertiseTools: true` or drop `effects`.",
+    });
+    return undefined;
+  }
+  const parsedTools = isInlineStdioConnection(connection)
+    ? { ok: true as const, value: undefined }
+    : parseConnectionTools(connection.tools);
+  if (!parsedTools.ok) {
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, entryPath),
+      message:
+        "MCP connection `tools` allowlist must be a non-empty array of tool names.",
+    });
+    return undefined;
+  }
+  if (
+    isInlineStdioConnection(connection) &&
+    connection.disallowedTools !== undefined
+  ) {
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, entryPath),
+      message:
+        "MCP connection `disallowedTools` is not supported on inline `tools` connections — author only the tools you want.",
+    });
+    return undefined;
+  }
+  const parsedDisallowed = isInlineStdioConnection(connection)
+    ? { ok: true as const, value: undefined }
+    : parseConnectionTools(connection.disallowedTools);
+  if (!parsedDisallowed.ok) {
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, entryPath),
+      message:
+        "MCP connection `disallowedTools` must be a non-empty array of tool names.",
+    });
+    return undefined;
+  }
+  if (
+    (parsedTools.value !== undefined || parsedDisallowed.value !== undefined) &&
+    role === "model" &&
+    connection.advertiseTools !== true
+  ) {
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, entryPath),
+      message:
+        "MCP connection `tools` / `disallowedTools` filter advertised tools; set `advertiseTools: true` or drop the name list. Put the connection in `agent/host-connections/` to restrict `host.mcp` only.",
+    });
+    return undefined;
+  }
+  if (
+    connection.advertiseTools === true &&
+    isInlineStdioConnection(connection)
+  ) {
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, entryPath),
+      message:
+        "MCP connection `advertiseTools` is not supported on inline `tools` connections — author those as agent/tools/ server tools instead.",
+    });
+    return undefined;
+  }
+  if (
+    connection.auth !== undefined &&
+    "url" in connection &&
+    connection.oauth === true
+  ) {
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, entryPath),
+      message:
+        "MCP connection `oauth: true` cannot be combined with `auth` (per-session headers): the host OAuth provider owns the Authorization header. Drop one of them.",
+    });
+    return undefined;
+  }
+  if (isInlineStdioConnection(connection)) {
+    return loadInlineStdioConnection(ctx, name, entryPath, connection);
+  }
+  if (
+    "url" in connection &&
+    connection.oauth === true &&
+    hasAuthorizationHeader(connection.headers)
+  ) {
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, entryPath),
+      message:
+        "MCP connection `oauth: true` cannot set an Authorization header. Drop the header or remove `oauth`.",
+    });
+    return undefined;
+  }
+  if (
+    "cursorAccount" in connection &&
+    connection.cursorAccount === true &&
+    cursorAccountServersHasMixedWildcard(connection.servers)
+  ) {
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, entryPath),
+      message:
+        'Cursor account MCP connection `servers` cannot mix `"*"` with connector names. Use `"*"` / `["*"]` (or omit `servers`) for every connected server, or list only concrete connector names.',
+    });
+    return undefined;
+  }
+  const transport = connectionTransport(connection);
+  if (transport === undefined) {
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, entryPath),
+      message:
+        "MCP connections require a `url` (http/sse), a `command` (stdio), `tools` (TypeScript packaged as stdio), an `agent` (peer agent slug on the same serve host), or `cursorAccount: true` (the Cursor account's MCP connectors).",
+    });
+    return undefined;
+  }
+  if (
+    "cursorAccount" in transport &&
+    transport.servers !== undefined &&
+    (transport.servers.length === 0 ||
+      transport.servers.some((server) => isBlank(server)))
+  ) {
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, entryPath),
+      message:
+        'Cursor account MCP connection `servers` must be a non-empty list of connector names, `"*"` / `["*"]` for every connected server, or omitted for the same all-connectors behavior.',
+    });
+    return undefined;
+  }
+  if ("agent" in transport && !NAME_PATTERN.test(transport.agent)) {
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, entryPath),
+      message: `Peer MCP connection agent "${transport.agent}" must be a mount slug matching ${NAME_PATTERN}.`,
+    });
+    return undefined;
+  }
+  return {
+    name,
+    transport,
+    description: connection.description,
+    auth: connection.auth,
+    advertiseTools: connection.advertiseTools,
+    effects: parsedEffects.value,
+    tools: parsedTools.value,
+    disallowedTools: parsedDisallowed.value,
+  };
+}
+
+async function loadInlineStdioConnection(
+  ctx: DiscoveryContext,
+  name: string,
+  entryPath: string,
+  connection: InlineStdioConnectionConfig & {
+    description?: string;
+  }
+): Promise<DiscoveredConnection | undefined> {
+  const tools = connection.tools;
+  const names = Object.keys(tools);
+  if (names.length === 0) {
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, entryPath),
+      message: "MCP connection `tools` must declare at least one tool.",
+    });
+    return undefined;
+  }
+  for (const toolName of names) {
+    if (!NAME_PATTERN.test(toolName)) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, entryPath),
+        message: `MCP tool name "${toolName}" must match ${NAME_PATTERN}.`,
+      });
+      return undefined;
+    }
+    const tool = tools[toolName];
+    if (tool === undefined || isBlank(tool.description)) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, entryPath),
+        message: `MCP tool "${toolName}" requires a non-empty description.`,
+      });
+      return undefined;
+    }
+    if (typeof tool.execute !== "function") {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, entryPath),
+        message: `MCP tool "${toolName}" requires an execute(input) function.`,
+      });
+      return undefined;
+    }
+  }
+  try {
+    const transport = await packageInlineStdioConnection({
+      name,
+      entryPath,
+      tools,
+      absWorkingDir: ctx.rootDir,
+    });
+    return {
+      name,
+      transport,
+      description: connection.description,
+    };
+  } catch (error) {
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, entryPath),
+      message: `Failed to package inline stdio MCP connection: ${errorMessage(error)}`,
+    });
+    return undefined;
+  }
+}

package/src/internal/discovery/context.ts

@@ -0,0 +1,46 @@
+/**
+ * Shared discovery state: the loader options, the per-project context every loader receives, and the diagnostic helpers.
+ */
+
+import { relative } from "node:path";
+import { pathToFileURL } from "node:url";
+import type { Diagnostic } from "../../types.js";
+import { toPosix } from "./fs.js";
+
+export interface LoadAgentProjectOptions {
+  /** Override the module loader (embedders / tests). */
+  importModule?: (absolutePath: string) => Promise<Record<string, unknown>>;
+}
+
+type ImportModule = (absolutePath: string) => Promise<Record<string, unknown>>;
+
+export async function defaultImportModule(
+  absolutePath: string
+): Promise<Record<string, unknown>> {
+  return (await import(pathToFileURL(absolutePath).href)) as Record<
+    string,
+    unknown
+  >;
+}
+
+export interface DiscoveryContext {
+  rootDir: string;
+  diagnostics: Diagnostic[];
+  importModule: ImportModule;
+}
+
+export function displayPath(
+  ctx: DiscoveryContext,
+  absolutePath: string
+): string {
+  const rel = relative(ctx.rootDir, absolutePath);
+  return rel.startsWith("..") ? absolutePath : toPosix(rel);
+}
+
+export function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+export function isBlank(value: unknown): boolean {
+  return typeof value !== "string" || value.trim() === "";
+}