@cursor/july 0.1.100 → 0.1.102

package/src/internal/discovery/schedules.ts

@@ -0,0 +1,94 @@
+/**
+ * `agent/schedules/*.ts`: cron-driven runs.
+ */
+
+import { readFile } from "node:fs/promises";
+import { basename, extname, relative } from "node:path";
+import type { DiscoveredSchedule, ScheduleDefinition } from "../../types.js";
+import { isValidCron } from "../cron.js";
+import { parseFrontmatter } from "../frontmatter.js";
+import { type DiscoveryContext, displayPath } from "./context.js";
+import { isDirectory, isModuleFile, toPosix, walkFiles } from "./fs.js";
+import { importDefault } from "./modules.js";
+
+export async function loadSchedules(
+  ctx: DiscoveryContext,
+  schedulesDir: string
+): Promise<DiscoveredSchedule[]> {
+  if (!(await isDirectory(schedulesDir))) {
+    return [];
+  }
+  const schedules: DiscoveredSchedule[] = [];
+  for (const filePath of await walkFiles(schedulesDir)) {
+    const rel = toPosix(relative(schedulesDir, filePath));
+    if (rel.endsWith(".md")) {
+      const name = rel.slice(0, -".md".length);
+      const { data, body } = parseFrontmatter(await readFile(filePath, "utf8"));
+      const cron = data.cron;
+      if (cron === undefined || !isValidCron(cron)) {
+        ctx.diagnostics.push({
+          severity: "error",
+          path: displayPath(ctx, filePath),
+          message:
+            cron === undefined
+              ? "Markdown schedules require `cron` frontmatter."
+              : `Invalid cron expression: "${cron}".`,
+        });
+        continue;
+      }
+      const markdown = body.trim();
+      if (markdown === "") {
+        ctx.diagnostics.push({
+          severity: "error",
+          path: displayPath(ctx, filePath),
+          message: "Markdown schedules require a non-empty prompt body.",
+        });
+        continue;
+      }
+      schedules.push({
+        name,
+        cron,
+        kind: "markdown",
+        definition: {
+          __agentServe: "schedule",
+          cron,
+          markdown,
+        },
+      });
+      continue;
+    }
+
+    if (!isModuleFile(basename(filePath))) {
+      continue;
+    }
+    const name = rel.slice(0, -extname(rel).length);
+    const definition = await importDefault(ctx, filePath, "schedule");
+    if (definition === undefined) {
+      continue;
+    }
+    const schedule = definition as ScheduleDefinition;
+    if ((schedule.markdown === undefined) === (schedule.run === undefined)) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, filePath),
+        message: "Schedules require exactly one of `markdown` or `run`.",
+      });
+      continue;
+    }
+    if (!isValidCron(schedule.cron)) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, filePath),
+        message: `Invalid cron expression: "${schedule.cron}".`,
+      });
+      continue;
+    }
+    schedules.push({
+      name,
+      cron: schedule.cron,
+      kind: schedule.run === undefined ? "markdown" : "run",
+      definition: schedule,
+    });
+  }
+  return schedules;
+}

package/src/internal/discovery/seed-files.ts

@@ -0,0 +1,37 @@
+/**
+ * `agent/sandbox/workspace/**`: files seeded into each local session workspace.
+ */
+
+import { join, relative } from "node:path";
+import type { SeedFile } from "../../types.js";
+import { type DiscoveryContext, displayPath } from "./context.js";
+import { isDirectory, isFile, toPosix, walkFiles } from "./fs.js";
+
+export async function loadSeedFiles(
+  ctx: DiscoveryContext,
+  agentDir: string
+): Promise<SeedFile[]> {
+  const sandboxDir = join(agentDir, "sandbox");
+  for (const candidate of ["sandbox.ts", join("sandbox", "sandbox.ts")]) {
+    if (await isFile(join(agentDir, candidate))) {
+      ctx.diagnostics.push({
+        severity: "warning",
+        path: displayPath(ctx, join(agentDir, candidate)),
+        message:
+          "Custom sandbox backends are not supported; the agent runs in the session workspace directory. Ignoring.",
+      });
+    }
+  }
+  const workspaceDir = join(sandboxDir, "workspace");
+  if (!(await isDirectory(workspaceDir))) {
+    return [];
+  }
+  const seedFiles: SeedFile[] = [];
+  for (const filePath of await walkFiles(workspaceDir)) {
+    seedFiles.push({
+      relativePath: toPosix(relative(workspaceDir, filePath)),
+      sourcePath: filePath,
+    });
+  }
+  return seedFiles;
+}

package/src/internal/discovery/services.ts

@@ -0,0 +1,124 @@
+/**
+ * `agent/storage.ts`, `agent/otel.ts`, `agent/artifacts.ts`: host services the agent configures.
+ */
+
+import { join } from "node:path";
+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:
+        '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;
+}
+
+/**
+ * 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,176 @@
+/**
+ * `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 { 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
+): 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, "skill");
+      if (definition === undefined) {
+        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.
+ */
+export 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,29 @@
+/**
+ * A subagent as the Cursor harness runs it: description, model, and prompt. Its other slots are inert.
+ */
+
+import type { ModelSetting, ResolvedAgent } from "../../types.js";
+import { withIdentityPreamble } from "../workspace.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: [],
+  };
+}

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);
+  }
+}