@cursor/july 0.1.101 → 0.1.103

package/src/internal/discovery/services.ts

@@ -0,0 +1,160 @@
+/**
+ * `agent/storage.ts`, `agent/otel.ts`, `agent/artifacts.ts`,
+ * `agent/result.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,
+  ResultDefinition,
+} 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:
+        'agent/storage.ts 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:
+      'agent/storage.ts (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;
+}
+
+export async function loadResult(
+  ctx: DiscoveryContext,
+  agentDir: string
+): Promise<ResultDefinition | undefined> {
+  const path = await findModuleFile(agentDir, "result");
+  if (path === undefined) {
+    return undefined;
+  }
+  const imported = await importDefault(ctx, path, "result");
+  if (imported === undefined) {
+    return undefined;
+  }
+  return imported as ResultDefinition;
+}
+
+/** 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,186 @@
+/**
+ * `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,136 @@
+/**
+ * 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: "warning",
+      path: displayPath(ctx, resultPath),
+      message: "result is not supported on subagents; ignoring.",
+    });
+  }
+  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"],
+    ["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,182 @@
+/**
+ * `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);
+  }
+}