@cursor/july 0.1.101 → 0.1.103

package/src/internal/discovery/project.ts

@@ -0,0 +1,341 @@
+/**
+ * Project roots and mounts: find agents under a directory and load them into {@link AgentProject} manifests.
+ */
+
+import { basename, join, resolve } from "node:path";
+import { httpChannel } from "../../channels.js";
+import type {
+  AgentProject,
+  ArtifactsDefinition,
+  Diagnostic,
+} from "../../types.js";
+import { registerAuthoredModuleLoaders } from "../authored-loaders.js";
+import {
+  applyAgentContinuationDefaults,
+  warnOmittedContinuationDowngrades,
+} from "../continuation-channel.js";
+import { loadABConfig, loadABs } from "./ab.js";
+import { loadAgent, warnUnknownSlots } from "./agent.js";
+import { loadChannels } from "./channels.js";
+import {
+  type DiscoveryContext,
+  defaultImportModule,
+  displayPath,
+  type LoadAgentProjectOptions,
+} from "./context.js";
+import {
+  hasFlatLayoutMarkers,
+  isDirectory,
+  readPackageName,
+  sortedEntries,
+} from "./fs.js";
+import { loadHooks } from "./hooks.js";
+import { NAME_PATTERN } from "./names.js";
+import { loadSchedules } from "./schedules.js";
+import {
+  appendArtifactTool,
+  loadArtifacts,
+  loadOtel,
+  loadResult,
+  loadStorage,
+  mergeArtifacts,
+} from "./services.js";
+
+/**
+ * True when `dir` looks like an agent project root: it has a nested `agent/`
+ * directory, or flat-layout markers (`agent.ts` / `instructions.md`) directly
+ * inside it.
+ */
+export async function isAgentProjectDir(dir: string): Promise<boolean> {
+  const resolved = resolve(dir);
+  if (!(await isDirectory(resolved))) {
+    return false;
+  }
+  if (await isDirectory(join(resolved, "agent"))) {
+    return true;
+  }
+  return hasFlatLayoutMarkers(resolved);
+}
+
+/** One immediate child agent directory under a multi-agent parent. */
+export interface ChildAgentDir {
+  slug: string;
+  dir: string;
+}
+
+/**
+ * List agent projects directly under `rootDir` (one level deep) without
+ * loading them. Empty when the path is missing or has no child agents.
+ * Slug rules match {@link loadAgentProjects} / multi-agent serve.
+ */
+export async function listChildAgentDirs(
+  rootDir: string
+): Promise<ChildAgentDir[]> {
+  const resolved = resolve(rootDir);
+  if (!(await isDirectory(resolved))) {
+    return [];
+  }
+
+  const results: ChildAgentDir[] = [];
+  const seenSlugs = new Set<string>();
+  for (const entry of await sortedEntries(resolved)) {
+    if (!entry.isDirectory() || entry.name.startsWith(".")) {
+      continue;
+    }
+    if (entry.name === "node_modules") {
+      continue;
+    }
+    const childDir = join(resolved, entry.name);
+    if (!(await isAgentProjectDir(childDir))) {
+      continue;
+    }
+    const slug = assertSlug(entry.name, resolved);
+    if (seenSlugs.has(slug)) {
+      throw new Error(`Duplicate agent slug "${slug}" under ${resolved}.`);
+    }
+    seenSlugs.add(slug);
+    results.push({ slug, dir: childDir });
+  }
+  return results;
+}
+
+/**
+ * Discover the agent projects directly under `rootDir` (one level deep):
+ * each immediate child directory that is itself an agent project becomes a
+ * mounted agent, keyed by a slug derived from its directory name. Used for
+ * multi-agent serving, where one server hosts many agents under
+ * `/<slug>/...`. Throws when no child projects are found.
+ */
+export async function loadAgentProjects(
+  rootDir: string,
+  options: LoadAgentProjectOptions = {}
+): Promise<Array<{ slug: string; project: AgentProject }>> {
+  const resolved = resolve(rootDir);
+  if (!(await isDirectory(resolved))) {
+    throw new Error(`Agent projects directory does not exist: ${resolved}`);
+  }
+
+  const children = await listChildAgentDirs(resolved);
+  if (children.length === 0) {
+    throw new Error(
+      `No agent projects found directly under ${resolved}. Each agent should be a subdirectory with its own agent/ directory (or flat-layout markers).`
+    );
+  }
+  const results: Array<{ slug: string; project: AgentProject }> = [];
+  // Storage namespaces (session mirror, host kv) key on the project
+  // NAME, not the mount slug — two co-hosted agents sharing a name would
+  // silently share sessions and KV state.
+  const slugByName = new Map<string, string>();
+  for (const child of children) {
+    const project = await loadAgentProject(child.dir, options);
+    const priorSlug = slugByName.get(project.name);
+    if (priorSlug !== undefined) {
+      throw new Error(
+        `Duplicate agent name "${project.name}" under ${resolved}: agents "${priorSlug}" and "${child.slug}" both resolve to it (package.json "name", or the directory name when unset). Co-hosted agents must have distinct names — their storage and session namespaces key on the name.`
+      );
+    }
+    slugByName.set(project.name, child.slug);
+    results.push({ slug: child.slug, project });
+  }
+  return results;
+}
+
+/**
+ * Resolve mounts for `serve` / CLI. Defaults to multi-agent layout:
+ * - `mode: "single"` — one agent at `/v1/*` (empty slug).
+ * - otherwise, if `rootDir` is itself an agent project — one agent under
+ *   `/<dirname>/...`.
+ * - otherwise, every immediate child agent project under `/<slug>/...`.
+ */
+export async function resolveAgentMounts(
+  rootDir: string,
+  options: LoadAgentProjectOptions & {
+    mode?: "single" | "multi";
+  } = {}
+): Promise<Array<{ slug: string; project: AgentProject }>> {
+  const { mode = "multi", ...discovery } = options;
+  if (mode === "single") {
+    return [{ slug: "", project: await loadAgentProject(rootDir, discovery) }];
+  }
+  if (await isAgentProjectDir(rootDir)) {
+    const resolved = resolve(rootDir);
+    const slug = assertSlug(basename(resolved), resolved);
+    return [
+      {
+        slug,
+        project: await loadAgentProject(rootDir, discovery),
+      },
+    ];
+  }
+  return loadAgentProjects(rootDir, discovery);
+}
+
+function assertSlug(name: string, parentDir: string): string {
+  if (!NAME_PATTERN.test(name) || RESERVED_SLUGS.has(name)) {
+    throw new Error(
+      `Cannot mount agent directory "${name}" under ${parentDir}: its name must match ${NAME_PATTERN} and not be one of ${[...RESERVED_SLUGS].join(", ")}.`
+    );
+  }
+  return name;
+}
+
+/** URL path segments reserved by the server; agents cannot use them as slugs. */
+const RESERVED_SLUGS: Set<string> = new Set(["v1", "playground", "docs"]);
+
+export async function loadAgentProject(
+  dir: string,
+  options: LoadAgentProjectOptions = {}
+): Promise<AgentProject> {
+  // Public API: embedders can call discovery directly (without `serve()` or
+  // the CLI), and it dynamically imports authored TypeScript.
+  await registerAuthoredModuleLoaders();
+  const rootDir = resolve(dir);
+  if (!(await isDirectory(rootDir))) {
+    throw new Error(`Agent project directory does not exist: ${rootDir}`);
+  }
+
+  const nestedAgentDir = join(rootDir, "agent");
+  let agentDir: string;
+  if (await isDirectory(nestedAgentDir)) {
+    agentDir = nestedAgentDir;
+  } else if (await hasFlatLayoutMarkers(rootDir)) {
+    agentDir = rootDir;
+  } else {
+    throw new Error(
+      `No agent found under ${rootDir}: expected an agent/ directory (or a flat layout with agent.ts / instructions.md at the root)`
+    );
+  }
+
+  const diagnostics: Diagnostic[] = [];
+  const ctx: DiscoveryContext = {
+    rootDir,
+    diagnostics,
+    importModule: options.importModule ?? defaultImportModule,
+  };
+
+  const name = (await readPackageName(rootDir)) ?? basename(rootDir);
+  const { agent, projectSlots } = await loadAgent(ctx, agentDir, {
+    name,
+    isRoot: true,
+  });
+
+  const { channels, httpChannelDefinition } = await loadChannels(
+    ctx,
+    join(agentDir, "channels")
+  );
+  for (const channel of projectSlots.channels) {
+    if (channel.id === "http" || channels.some((c) => c.id === channel.id)) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, join(agentDir, "extensions")),
+        message: `Extension channel "${channel.id}" collides with an agent channel.`,
+      });
+      continue;
+    }
+    channels.push(channel);
+  }
+  const schedules = await loadSchedules(ctx, join(agentDir, "schedules"));
+  schedules.push(...projectSlots.schedules);
+  const hooks = await loadHooks(ctx, join(agentDir, "hooks"));
+  hooks.push(...projectSlots.hooks);
+  const abs = await loadABs(ctx, agentDir);
+  for (const experiment of projectSlots.abs) {
+    if (abs.some((existing) => existing.name === experiment.name)) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, join(agentDir, "extensions")),
+        message: `Extension A/B experiment "${experiment.name}" collides with an agent experiment.`,
+      });
+      continue;
+    }
+    abs.push(experiment);
+  }
+  const abConfig = await loadABConfig(ctx, agentDir);
+  const storage = await loadStorage(ctx, agentDir, agent.architecture);
+  const artifacts = await mergeProjectArtifacts(
+    ctx,
+    agentDir,
+    projectSlots.artifacts
+  );
+  const otel = await loadOtel(ctx, agentDir);
+  const result = await loadResult(ctx, agentDir);
+  await appendArtifactTool(ctx, agentDir, agent, artifacts);
+
+  if (agentDir !== rootDir) {
+    await warnUnknownSlots(ctx, agentDir);
+  }
+
+  const resolvedHttpChannel = httpChannelDefinition ?? httpChannel();
+  warnOmittedContinuationDowngrades({
+    architecture: agent.architecture,
+    channels,
+    warn: (id, message) => {
+      ctx.diagnostics.push({
+        severity: "warning",
+        path: displayPath(ctx, join(agentDir, "channels", `${id}.ts`)),
+        message,
+      });
+    },
+  });
+  applyAgentContinuationDefaults({
+    agent,
+    channels,
+    httpChannel: resolvedHttpChannel,
+  });
+
+  return {
+    rootDir,
+    agentDir,
+    name: agent.name,
+    agent,
+    httpChannel: resolvedHttpChannel,
+    channels,
+    schedules,
+    hooks,
+    abs,
+    abConfig,
+    storage,
+    artifacts,
+    result,
+    otel,
+    diagnostics,
+  };
+}
+
+async function mergeProjectArtifacts(
+  ctx: DiscoveryContext,
+  agentDir: string,
+  extra: ArtifactsDefinition | undefined
+): Promise<ArtifactsDefinition | undefined> {
+  const agent = await loadArtifacts(ctx, agentDir);
+  if (extra === undefined) {
+    return agent;
+  }
+  const kinds = { ...extra.kinds };
+  const agentKinds = agent?.kinds;
+  for (const kind of Object.keys(kinds)) {
+    if (agentKinds !== undefined && kind in agentKinds) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, join(agentDir, "extensions")),
+        message: `Extension artifact kind "${kind}" collides with an agent kind.`,
+      });
+      delete kinds[kind];
+    }
+  }
+  return mergeArtifacts(agent, { ...extra, kinds });
+}
+
+/** True when the project has diagnostics that must block serving. */
+export function hasErrorDiagnostics(project: AgentProject): boolean {
+  return project.diagnostics.some((d) => d.severity === "error");
+}
+
+export function formatDiagnostics(diagnostics: Diagnostic[]): string {
+  return diagnostics
+    .map((d) => {
+      const location = d.path === undefined ? "" : ` (${d.path})`;
+      return `${d.severity}: ${d.message}${location}`;
+    })
+    .join("\n");
+}

package/src/internal/discovery/runtime.ts

@@ -0,0 +1,158 @@
+/**
+ * Runtime resolution and the limitations each runtime imposes on the authored surface.
+ */
+
+import { join } from "node:path";
+import type { AgentRuntime } from "../../types.js";
+import { type DiscoveryContext, displayPath } from "./context.js";
+
+/**
+ * Validate the authored runtime. An unrecognized value is an error
+ * diagnostic and falls back to local — a typo must not silently pick a
+ * different harness for every turn.
+ */
+export function resolveRuntime(
+  ctx: DiscoveryContext,
+  agentDir: string,
+  runtime: AgentRuntime | undefined
+): AgentRuntime {
+  if (
+    runtime === undefined ||
+    runtime === "local" ||
+    runtime === "cloud" ||
+    runtime === "grokbot"
+  ) {
+    return runtime ?? "local";
+  }
+  ctx.diagnostics.push({
+    severity: "error",
+    path: displayPath(ctx, join(agentDir, "agent.ts")),
+    message: `runtime must be "local", "cloud", or "grokbot"; got ${JSON.stringify(runtime)}.`,
+  });
+  return "local";
+}
+
+/**
+ * Grok Bot turns run on the Sand harness with its own toolset: authored
+ * server tools, MCP connections, and subagents have no path onto that
+ * toolset yet, so an agent declaring them must fail at serve start rather
+ * than run with capabilities silently missing.
+ */
+export function checkGrokBotRuntimeLimitations(
+  ctx: DiscoveryContext,
+  agentDir: string,
+  counts: {
+    serverTools: number;
+    agentTools: number;
+    skills: number;
+    seedFiles: number;
+    connections: number;
+    subagents: number;
+    hasCloudOptions: boolean;
+    hasLocalSandbox: boolean;
+  }
+): void {
+  const agentPath = displayPath(ctx, join(agentDir, "agent.ts"));
+  const error = (path: string, message: string): void => {
+    ctx.diagnostics.push({ severity: "error", path, message });
+  };
+  const warn = (path: string, message: string): void => {
+    ctx.diagnostics.push({ severity: "warning", path, message });
+  };
+  if (counts.serverTools > 0) {
+    error(
+      displayPath(ctx, join(agentDir, "tools")),
+      'Server tools (execution: "server", including opted-in builtinTools) are not reachable from grokbot turns yet. Remove them or run the agent on the local runtime.'
+    );
+  }
+  if (counts.connections > 0) {
+    error(
+      displayPath(ctx, agentDir),
+      "MCP connections (agent/mcp-connections/ or agent/host-connections/) are not wired into grokbot turns yet. Remove them or run the agent on the local runtime."
+    );
+  }
+  if (counts.subagents > 0) {
+    error(
+      displayPath(ctx, join(agentDir, "subagents")),
+      "Authored subagents are not available on grokbot turns (the Grok Bot harness runs its own subagent set). Remove them or run the agent on the local runtime."
+    );
+  }
+  // The remaining declarations mirror the cloud runtime's warnings: the
+  // turn runs on a hosted machine (the account's box), so local-workspace
+  // materialization never reaches it.
+  if (counts.agentTools > 0) {
+    warn(
+      displayPath(ctx, join(agentDir, "tools")),
+      'Agent tools (execution: "agent") are described in the hosted session\'s instructions (with script bodies); they are not written onto the box filesystem automatically.'
+    );
+  }
+  if (counts.skills > 0) {
+    warn(
+      displayPath(ctx, join(agentDir, "skills")),
+      "Authored skills are materialized into the local session workspace only; the hosted Grok Bot box does not see them."
+    );
+  }
+  if (counts.seedFiles > 0) {
+    warn(
+      displayPath(ctx, join(agentDir, "sandbox")),
+      "sandbox/workspace seed files apply to the local session workspace only; grokbot turns run on the account's hosted box."
+    );
+  }
+  if (counts.hasCloudOptions) {
+    warn(
+      agentPath,
+      'The `cloud` block is unused on runtime: "grokbot", and grokbot sessions refuse per-session cloud attach.'
+    );
+  }
+  if (counts.hasLocalSandbox) {
+    warn(
+      agentPath,
+      'local.sandbox does not apply to runtime: "grokbot"; the box is the account\'s Cursor-hosted computer.'
+    );
+  }
+}
+
+export function warnCloudRuntimeLimitations(
+  ctx: DiscoveryContext,
+  agentDir: string,
+  counts: {
+    agentTools: number;
+    skills: number;
+    seedFiles: number;
+    hasCloudOptions: boolean;
+  }
+): void {
+  const agentPath = displayPath(ctx, join(agentDir, "agent.ts"));
+  if (!counts.hasCloudOptions) {
+    ctx.diagnostics.push({
+      severity: "warning",
+      path: agentPath,
+      message:
+        'runtime: "cloud" usually needs a `cloud` block (e.g. repos / env). Without it the Cursor cloud API may reject create.',
+    });
+  }
+  if (counts.agentTools > 0) {
+    ctx.diagnostics.push({
+      severity: "warning",
+      path: displayPath(ctx, join(agentDir, "tools")),
+      message:
+        'Agent tools (execution: "agent") are described on the first cloud prompt (with script bodies); they are not written into the cloud VM filesystem automatically.',
+    });
+  }
+  if (counts.skills > 0) {
+    ctx.diagnostics.push({
+      severity: "warning",
+      path: displayPath(ctx, join(agentDir, "skills")),
+      message:
+        "Authored skills reach cloud agents through native store discovery: hosted deployments write the deployment store's skills/ directory; local serve/run with a personal API key writes agent-serve/<agent>/skills/ on the USER store. Without a reachable store, only skills already in the cloud repo are visible.",
+    });
+  }
+  if (counts.seedFiles > 0) {
+    ctx.diagnostics.push({
+      severity: "warning",
+      path: displayPath(ctx, join(agentDir, "sandbox")),
+      message:
+        "sandbox/workspace seed files reach cloud agents through the Agent Store, not the checkout: hosted deployments write the deployment store's workspace/ directory; local serve/run with a personal API key writes agent-serve/<agent>/workspace/ on the USER store. The first cloud prompt names the mounted directory. Without a reachable store, cloud turns do not see them.",
+    });
+  }
+}

package/src/internal/discovery/schedules.ts

@@ -0,0 +1,120 @@
+/**
+ * `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 { getDefinitionKind } from "../brand.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,
+  onDisable?: (name: string, path: string) => void
+): 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);
+      if (name.includes("__")) {
+        ctx.diagnostics.push({
+          severity: "error",
+          path: displayPath(ctx, filePath),
+          message: `Schedule name "${name}" may not contain "__"; it is reserved for extension contributions (\`<ns>__<name>\`).`,
+        });
+        continue;
+      }
+      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);
+    if (name.includes("__")) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, filePath),
+        message: `Schedule name "${name}" may not contain "__"; it is reserved for extension contributions (\`<ns>__<name>\`).`,
+      });
+      continue;
+    }
+    const definition = await importDefault(
+      ctx,
+      filePath,
+      onDisable === undefined ? "schedule" : ["schedule", "disabled"]
+    );
+    if (definition === undefined) {
+      continue;
+    }
+    if (getDefinitionKind(definition) === "disabled") {
+      onDisable?.(name, filePath);
+      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;
+}