@cursor/bdk 0.2.3 → 0.2.5

package/src/internal/discovery/channels.ts

@@ -1,100 +0,0 @@
-/**
- * `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"
-              ? "The built-in HTTP session channel belongs to the agent; an extension cannot contribute it."
-              : "The built-in HTTP session channel is reserved for the `http` channel id.",
-        });
-        continue;
-      }
-      httpChannelDefinition = mod.default as HttpChannelDefinition;
-      continue;
-    }
-
-    if (kind !== "channel") {
-      ctx.diagnostics.push({
-        severity: "error",
-        path: displayPath(ctx, entryPath),
-        message:
-          id === "http" && mode === "agent"
-            ? "The channel id `http` is reserved for the built-in HTTP session channel."
-            : "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 session channel.",
-      });
-      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

@@ -1,516 +0,0 @@
-/**
- * `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 { unresolvedConnectionEnvNames } from "../connection-env.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 the model connection of the same 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. Model connections are always visible to the model. Put privileged servers in 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;
-  }
-  if (connection.optional !== undefined && typeof connection.optional !== "boolean") {
-    ctx.diagnostics.push({
-      severity: "error",
-      path: displayPath(ctx, entryPath),
-      message: "MCP connection `optional` must be a boolean.",
-    });
-    return undefined;
-  }
-  if (connection.optional === true && connection.advertiseTools !== true) {
-    ctx.diagnostics.push({
-      severity: "error",
-      path: displayPath(ctx, entryPath),
-      message:
-        "MCP connection `optional` skips advertised listing failures; set `advertiseTools: true` or drop `optional`.",
-    });
-    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 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 under tools/ as 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;
-  }
-  // A warning, never an error: templates resolve when the connection opens,
-  // and a hosted deployment binds its secrets after discovery has run.
-  const unresolved = unresolvedConnectionEnvNames(transport);
-  if (unresolved.length > 0) {
-    ctx.diagnostics.push({
-      severity: "warning",
-      path: displayPath(ctx, entryPath),
-      message: `MCP connection "${name}" templates ${unresolved.map(variable => `\${${variable}}`).join(", ")}, which the environment does not set. The value resolves when the connection opens, so hosted deployments are fine; locally, set it before the turn or the credential is empty.`,
-    });
-  }
-  return {
-    name,
-    transport,
-    description: connection.description,
-    auth: connection.auth,
-    advertiseTools: connection.advertiseTools,
-    optional: connection.optional,
-    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

@@ -1,38 +0,0 @@
-/**
- * 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() === "";
-}