@cursor/bdk 0.2.1

package/src/internal/discovery/services.ts

@@ -0,0 +1,151 @@
+/**
+ * `agent/storage.ts`, `agent/otel.ts`, `agent/artifacts.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 } from "../../types.js";
+import { artifactBuiltinTool, TAG_ARTIFACT_TOOL_NAME } from "../builtin-tools/index.js";
+import { type DiscoveryContext, displayPath } from "./context.js";
+import { findModuleFile } from "./fs.js";
+import { importDefault } from "./modules.js";
+
+export async function loadStorage(
+  ctx: DiscoveryContext,
+  agentDir: string,
+  architecture: AgentArchitecture | undefined,
+): Promise<StorageDefinition | undefined> {
+  const path = await findModuleFile(agentDir, "storage");
+  if (path === undefined) {
+    return undefined;
+  }
+  if (architecture === "v2") {
+    // Storage is a hosting-mode decision on v2, made by
+    // framework-storage-selection.ts: the state root when self-hosted,
+    // Cursor-managed storage on Cursor hosting. Fail early (error
+    // diagnostics refuse serve and deploy) rather than silently running
+    // with storage the author believes they configured. Not imported.
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, path),
+      message:
+        'defineStorage is not supported on architecture "v2": the platform selects storage (the local state root when self-hosted; Cursor-managed storage on Cursor hosting). Delete the file.',
+    });
+    return undefined;
+  }
+  // v1 keeps loading the authored sink, with notice: defineStorage is going
+  // away with the v1 control plane.
+  ctx.diagnostics.push({
+    severity: "warning",
+    path: displayPath(ctx, path),
+    message:
+      'defineStorage is deprecated and going away: architecture "v2" selects storage automatically (the local state root when self-hosted; Cursor-managed storage on Cursor hosting). Still honored on v1.',
+  });
+  const definition = await importDefault(ctx, path, "storage");
+  return definition as StorageDefinition | undefined;
+}
+
+export async function loadOtel(
+  ctx: DiscoveryContext,
+  agentDir: string,
+): Promise<OtelDefinition | undefined> {
+  const path = await findModuleFile(agentDir, "otel");
+  if (path === undefined) {
+    return undefined;
+  }
+  const definition = await importDefault(ctx, path, "otel");
+  return definition as OtelDefinition | undefined;
+}
+
+export async function loadArtifacts(
+  ctx: DiscoveryContext,
+  agentDir: string,
+): Promise<ArtifactsDefinition | undefined> {
+  const path = await findModuleFile(agentDir, "artifacts");
+  if (path === undefined) {
+    return undefined;
+  }
+  const imported = await importDefault(ctx, path, "artifacts");
+  if (imported === undefined) {
+    return undefined;
+  }
+  const definition = imported as ArtifactsDefinition;
+  if (definition.agentTool === true && Object.keys(definition.kinds ?? {}).length === 0) {
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, path),
+      message:
+        "artifacts.agentTool requires kinds: the tag_artifact tool needs at least one declared kind; its descriptions are the tool prompt.",
+    });
+  }
+  return definition;
+}
+
+/**
+ * `defineResult` / `agent/result.ts` is gone. A leftover file is an
+ * authoring error so discovery fails closed instead of silently ignoring
+ * host actuation that no longer runs.
+ */
+export async function rejectLegacyResult(ctx: DiscoveryContext, agentDir: string): Promise<void> {
+  const path = await findModuleFile(agentDir, "result");
+  if (path === undefined) {
+    return;
+  }
+  ctx.diagnostics.push({
+    severity: "error",
+    path: displayPath(ctx, path),
+    message:
+      "agent/result.ts is no longer supported; defineResult has been removed. Record structured output with an authored tool and actuate from a turn.completed hook.",
+  });
+}
+
+/** 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
+ * generated from the artifacts kinds registry, not `AgentConfig.builtinTools`.
+ */
+export async function appendArtifactTool(
+  ctx: DiscoveryContext,
+  agentDir: string,
+  agent: ResolvedAgent,
+  artifacts: ArtifactsDefinition | undefined,
+): Promise<void> {
+  const tool = artifactBuiltinTool(artifacts);
+  if (tool === undefined) {
+    return;
+  }
+  const artifactsPath = displayPath(
+    ctx,
+    (await findModuleFile(agentDir, "artifacts")) ?? join(agentDir, "artifacts.ts"),
+  );
+  if (agent.tools.some(t => t.name === TAG_ARTIFACT_TOOL_NAME)) {
+    ctx.diagnostics.push({
+      severity: "warning",
+      path: artifactsPath,
+      message: `Authored tool "${TAG_ARTIFACT_TOOL_NAME}" shadows the built-in tool of the same name; the authored tool wins.`,
+    });
+    return;
+  }
+  agent.tools.push(tool);
+}

package/src/internal/discovery/skills.ts

@@ -0,0 +1,174 @@
+/**
+ * `agent/skills/*`: markdown, packaged, and `defineSkill` skills.
+ */
+
+import { readFile } from "node:fs/promises";
+import { join, relative } from "node:path";
+import type {
+  DiscoveredSkill,
+  SkillConfig,
+  SkillDefinition,
+  SkillFileSource,
+} from "../../types.js";
+import { getDefinitionKind } from "../brand.js";
+import { parseFrontmatter } from "../frontmatter.js";
+import { type DiscoveryContext, displayPath, isBlank } from "./context.js";
+import {
+  isDirectory,
+  isFile,
+  isModuleFile,
+  moduleStem,
+  sortedEntries,
+  toPosix,
+  walkFiles,
+} from "./fs.js";
+import { importDefault } from "./modules.js";
+import { validateName } from "./names.js";
+
+/** Declared frontmatter, else the body's first line, else a generic line. */
+export function skillDescription(name: string, declared: string | undefined, body: string): string {
+  return declared ?? deriveSkillDescription(body) ?? `Instructions for the ${name} skill.`;
+}
+
+/** A packaged skill's sibling files, keyed by path relative to the skill dir. */
+export async function skillFiles(skillDir: string): Promise<Record<string, SkillFileSource>> {
+  const files: Record<string, SkillFileSource> = {};
+  for (const filePath of await walkFiles(skillDir)) {
+    const rel = toPosix(relative(skillDir, filePath));
+    if (rel !== "SKILL.md") {
+      files[rel] = { sourcePath: filePath };
+    }
+  }
+  return files;
+}
+
+export async function loadSkills(
+  ctx: DiscoveryContext,
+  skillsDir: string,
+  onDisable?: (name: string, path: string) => void,
+): Promise<DiscoveredSkill[]> {
+  if (!(await isDirectory(skillsDir))) {
+    return [];
+  }
+  const skills: DiscoveredSkill[] = [];
+  for (const entry of await sortedEntries(skillsDir)) {
+    const entryPath = join(skillsDir, entry.name);
+    if (entry.isDirectory()) {
+      const skill = await loadPackagedSkill(ctx, entryPath, entry.name);
+      if (skill !== undefined) {
+        skills.push(skill);
+      }
+      continue;
+    }
+    if (!entry.isFile()) {
+      continue;
+    }
+    if (entry.name.endsWith(".md")) {
+      const name = entry.name.slice(0, -".md".length);
+      if (!validateName(ctx, "skill", name, entryPath)) {
+        continue;
+      }
+      const { data, body } = parseFrontmatter(await readFile(entryPath, "utf8"));
+      skills.push({
+        name,
+        description: skillDescription(name, data.description, body),
+        markdown: body.trim(),
+        files: {},
+      });
+      continue;
+    }
+    if (isModuleFile(entry.name)) {
+      const name = moduleStem(entry.name);
+      if (!validateName(ctx, "skill", name, entryPath)) {
+        continue;
+      }
+      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));
+    }
+  }
+  return skills;
+}
+
+/** A skill whose body and sibling files are in memory (`defineSkill`, extensions). */
+function compileSkill(name: string, skill: SkillConfig): DiscoveredSkill {
+  const files: Record<string, SkillFileSource> = {};
+  for (const [rel, contents] of Object.entries(skill.files ?? {})) {
+    files[rel] = { contents };
+  }
+  return {
+    name,
+    description: skillDescription(name, skill.description, skill.markdown),
+    markdown: skill.markdown.trim(),
+    files,
+  };
+}
+
+async function loadPackagedSkill(
+  ctx: DiscoveryContext,
+  skillDir: string,
+  name: string,
+): Promise<DiscoveredSkill | undefined> {
+  const skillMdPath = join(skillDir, "SKILL.md");
+  if (!(await isFile(skillMdPath))) {
+    ctx.diagnostics.push({
+      severity: "warning",
+      path: displayPath(ctx, skillDir),
+      message: "Skill directories must contain a SKILL.md; ignoring.",
+    });
+    return undefined;
+  }
+  if (!validateName(ctx, "skill", name, skillDir)) {
+    return undefined;
+  }
+  const { data, body } = parseFrontmatter(await readFile(skillMdPath, "utf8"));
+  if (data.description === undefined || isBlank(data.description)) {
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, skillMdPath),
+      message:
+        "Packaged skills require `description` frontmatter in SKILL.md (there is no filename slug to fall back on).",
+    });
+    return undefined;
+  }
+
+  return {
+    name,
+    description: data.description,
+    markdown: body.trim(),
+    files: await skillFiles(skillDir),
+  };
+}
+
+/**
+ * Advertise the first non-empty, non-code-fence line of the body, with any
+ * leading `#`, `>`, `*`, or `-` markers stripped.
+ */
+function deriveSkillDescription(markdown: string): string | undefined {
+  let inFence = false;
+  for (const rawLine of markdown.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (line.startsWith("```")) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence || line === "") {
+      continue;
+    }
+    const stripped = line.replace(/^[#>*\s-]+/, "").trim();
+    if (stripped !== "") {
+      return stripped.length > 200 ? `${stripped.slice(0, 197)}...` : stripped;
+    }
+  }
+  return undefined;
+}

package/src/internal/discovery/subagent.ts

@@ -0,0 +1,138 @@
+/**
+ * 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;
+  model?: ModelSetting;
+  /** Authored prompt; the identity preamble is prepended. */
+  prompt?: string;
+}
+
+export function subagent(name: string, fields: SubagentFields): ResolvedAgent {
+  return {
+    name,
+    description: fields.description,
+    model: fields.model,
+    instructions: withIdentityPreamble(name, fields.prompt),
+    runtime: "local",
+    tools: [],
+    skills: [],
+    connections: [],
+    hostConnections: [],
+    subagents: [],
+    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: "error",
+      path: displayPath(ctx, resultPath),
+      message:
+        "agent/result.ts is no longer supported; defineResult has been removed. Record structured output with an authored tool and actuate from a turn.completed hook.",
+    });
+  }
+  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"],
+    ["reminders", "reminders"],
+    ["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/tools.ts

@@ -0,0 +1,170 @@
+/**
+ * `agent/tools/*.ts`: typed tools and the built-in tools appended after them.
+ */
+
+import { join } from "node:path";
+import type {
+  BuiltinToolsConfig,
+  DiscoveredTool,
+  ToolDefinition,
+  ToolEffect,
+} from "../../types.js";
+import { builtinTools } from "../builtin-tools/index.js";
+import { toolInputJsonSchema, toolOutputJsonSchema } from "../json-schema.js";
+import { type DiscoveryContext, displayPath, errorMessage, isBlank } from "./context.js";
+import { importDefault, moduleEntries } from "./modules.js";
+
+export async function loadTools(
+  ctx: DiscoveryContext,
+  toolsDir: string,
+): Promise<DiscoveredTool[]> {
+  const tools: DiscoveredTool[] = [];
+  for (const { name, path } of await moduleEntries(ctx, toolsDir, "tool")) {
+    const definition = await importDefault(ctx, path, "tool");
+    if (definition === undefined) {
+      continue;
+    }
+    const tool = compileTool(ctx, path, name, definition as ToolDefinition);
+    if (tool !== undefined) {
+      tools.push(tool);
+    }
+  }
+  return tools;
+}
+
+/**
+ * Validate one tool definition against the tool contract and convert its
+ * schemas. Diagnostics point at `entryPath` (the authored file, or the
+ * extension mount that contributed the tool).
+ */
+export function compileTool(
+  ctx: DiscoveryContext,
+  entryPath: string,
+  name: string,
+  tool: ToolDefinition,
+): DiscoveredTool | undefined {
+  if (isBlank(tool.description)) {
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, entryPath),
+      message: "Tools require a non-empty description.",
+    });
+    return undefined;
+  }
+  const execution = tool.execution === "agent" ? "agent" : "server";
+  const needsApprovalConfigured =
+    tool.needsApproval === true || typeof tool.needsApproval === "function";
+  const effect = declaredEffect(tool);
+  if (execution === "agent") {
+    if (isBlank(tool.script)) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, entryPath),
+        message:
+          'Tools with execution: "agent" require a non-empty `script` (shell body; JSON on stdin, result on stdout).',
+      });
+      return undefined;
+    }
+    if (typeof tool.execute === "function") {
+      ctx.diagnostics.push({
+        severity: "warning",
+        path: displayPath(ctx, entryPath),
+        message:
+          '`execute` is ignored when execution is "agent"; the Cursor agent runs `script` instead.',
+      });
+    }
+    if (needsApprovalConfigured) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, entryPath),
+        message: '`needsApproval` is only supported for execution: "server" tools (in-process).',
+      });
+      return undefined;
+    }
+  } else if (typeof tool.execute !== "function") {
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, entryPath),
+      message:
+        'Tools require an execute(input, ctx) function (or set execution: "agent" with a script).',
+    });
+    return undefined;
+  }
+  let inputSchema: DiscoveredTool["inputSchema"];
+  try {
+    inputSchema = toolInputJsonSchema(tool.inputSchema);
+  } catch (error) {
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, entryPath),
+      message: `Failed to convert inputSchema to JSON Schema: ${errorMessage(error)}`,
+    });
+    return undefined;
+  }
+  let outputSchema: DiscoveredTool["outputSchema"];
+  try {
+    outputSchema = toolOutputJsonSchema(tool.outputSchema);
+  } catch (error) {
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, entryPath),
+      message: `Failed to convert outputSchema to JSON Schema: ${errorMessage(error)}`,
+    });
+    return undefined;
+  }
+  return {
+    name,
+    description: tool.description,
+    inputSchema,
+    outputSchema,
+    execution,
+    needsApproval: needsApprovalConfigured,
+    effect,
+    script: execution === "agent" ? tool.script : undefined,
+    definition: tool,
+  };
+}
+
+/**
+ * Static view of a tool's `effect` for the manifest: the literal when it is
+ * one, `"dynamic"` for a per-call predicate, `undefined` when undeclared. A
+ * malformed value is left undeclared rather than guessed — undeclared is the
+ * safe state (a dry run stubs it), where a guess could be the unsafe one.
+ */
+function declaredEffect(tool: ToolDefinition): ToolEffect | "dynamic" | undefined {
+  if (typeof tool.effect === "function") {
+    return "dynamic";
+  }
+  return tool.effect === "read" || tool.effect === "write" ? tool.effect : undefined;
+}
+
+/**
+ * Append enabled built-in tools after authored tools. Authored tools with
+ * the same name win.
+ */
+export function appendBuiltinTools(
+  ctx: DiscoveryContext,
+  agentDir: string,
+  tools: DiscoveredTool[],
+  config: BuiltinToolsConfig | undefined,
+): void {
+  const builtin = builtinTools(config);
+  if (builtin.length === 0) {
+    return;
+  }
+  const agentPath = displayPath(ctx, join(agentDir, "agent.ts"));
+  for (const tool of builtin) {
+    const existing = tools.find(t => t.name === tool.name);
+    if (existing !== undefined) {
+      const owner =
+        existing.extension === undefined ? "Authored" : `Extension "${existing.extension}"`;
+      ctx.diagnostics.push({
+        severity: "warning",
+        path: agentPath,
+        message: `${owner} tool "${tool.name}" shadows the built-in tool of the same name; the built-in is skipped.`,
+      });
+      continue;
+    }
+    tools.push(tool);
+  }
+}

package/src/internal/discovery.ts

@@ -0,0 +1,27 @@
+/**
+ * Filesystem discovery: walks a project's `bot/` directory and compiles
+ * the authored files (markdown and TypeScript) into an {@link AgentProject}
+ * manifest. Identity comes from the path — a tool at `bot/tools/foo.ts`
+ * is named `foo`, a subagent at `bot/subagents/researcher/` is named
+ * `researcher` — so no definition carries a `name` field.
+ *
+ * The loaders live under `./discovery/`, one module per authored slot;
+ * this module is the public surface the CLI, server, and tests import.
+ */
+
+export {
+  DEFAULT_AGENT_ARCHITECTURE,
+  runtimeArchitectureCompatibilityError,
+} from "./discovery/agent-config.js";
+export type { LoadAgentProjectOptions } from "./discovery/context.js";
+export { projectInfo } from "./discovery/info.js";
+export {
+  type ChildAgentDir,
+  formatDiagnostics,
+  hasErrorDiagnostics,
+  isAgentProjectDir,
+  listChildAgentDirs,
+  loadAgentProject,
+  loadAgentProjects,
+  resolveAgentMounts,
+} from "./discovery/project.js";