@cursor/bdk 0.2.3 → 0.2.4

package/src/internal/discovery/services.ts

@@ -1,151 +0,0 @@
-/**
- * `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

@@ -1,174 +0,0 @@
-/**
- * `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

@@ -1,138 +0,0 @@
-/**
- * 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

@@ -1,170 +0,0 @@
-/**
- * `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

@@ -1,27 +0,0 @@
-/**
- * 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";