@cursor/july 0.1.101 → 0.1.102

package/src/internal/discovery/instructions.ts

@@ -0,0 +1,113 @@
+/**
+ * `agent/instructions.md` (or `.ts`, or a directory): the always-on system prompt.
+ */
+
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import type {
+  AgentConfigDefinition,
+  InstructionsDefinition,
+} from "../../types.js";
+import { getDefinitionKind } from "../brand.js";
+import {
+  type DiscoveryContext,
+  displayPath,
+  errorMessage,
+  isBlank,
+} from "./context.js";
+import {
+  findModuleFile,
+  isDirectory,
+  isFile,
+  isModuleFile,
+  sortedEntries,
+} from "./fs.js";
+
+export async function loadInstructions(
+  ctx: DiscoveryContext,
+  agentDir: string,
+  config: AgentConfigDefinition | undefined,
+  isRoot: boolean
+): Promise<string | undefined> {
+  const parts: string[] = [];
+
+  const markdownPath = join(agentDir, "instructions.md");
+  if (await isFile(markdownPath)) {
+    parts.push((await readFile(markdownPath, "utf8")).trim());
+  }
+
+  const modulePath = await findModuleFile(agentDir, "instructions");
+  if (modulePath !== undefined) {
+    const loaded = await loadInstructionsModule(ctx, modulePath);
+    if (loaded !== undefined) {
+      parts.push(loaded);
+    }
+  }
+
+  const instructionsDir = join(agentDir, "instructions");
+  if (await isDirectory(instructionsDir)) {
+    for (const entry of await sortedEntries(instructionsDir)) {
+      if (!entry.isFile()) {
+        continue;
+      }
+      const entryPath = join(instructionsDir, entry.name);
+      if (entry.name.endsWith(".md")) {
+        parts.push((await readFile(entryPath, "utf8")).trim());
+      } else if (isModuleFile(entry.name)) {
+        const loaded = await loadInstructionsModule(ctx, entryPath);
+        if (loaded !== undefined) {
+          parts.push(loaded);
+        }
+      }
+    }
+  }
+
+  if (config?.instructions !== undefined && !isBlank(config.instructions)) {
+    parts.push(config.instructions.trim());
+  }
+
+  const combined = parts.filter((part) => part !== "").join("\n\n");
+  if (combined === "") {
+    if (isRoot) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, markdownPath),
+        message:
+          "instructions.md is required on the root agent (the always-on system prompt).",
+      });
+    }
+    return undefined;
+  }
+  return combined;
+}
+
+async function loadInstructionsModule(
+  ctx: DiscoveryContext,
+  modulePath: string
+): Promise<string | undefined> {
+  let mod: Record<string, unknown>;
+  try {
+    mod = await ctx.importModule(modulePath);
+  } catch (error) {
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, modulePath),
+      message: `Failed to load module: ${errorMessage(error)}`,
+    });
+    return undefined;
+  }
+  const value = mod.default;
+  if (typeof value === "string") {
+    return value.trim();
+  }
+  if (getDefinitionKind(value) === "instructions") {
+    return (value as InstructionsDefinition).markdown.trim();
+  }
+  ctx.diagnostics.push({
+    severity: "error",
+    path: displayPath(ctx, modulePath),
+    message:
+      "Instructions modules must default-export a string or defineInstructions({ markdown }).",
+  });
+  return undefined;
+}

package/src/internal/discovery/modules.ts

@@ -0,0 +1,107 @@
+/**
+ * Walk a slot's module files, import one, and check that its default export carries an expected definition brand.
+ */
+
+import { join } from "node:path";
+import type { DefinitionKind } from "../../types.js";
+import { getDefinitionKind } from "../brand.js";
+import { type DiscoveryContext, displayPath, errorMessage } from "./context.js";
+import { isDirectory, isModuleFile, moduleStem, sortedEntries } from "./fs.js";
+import { validateName } from "./names.js";
+
+type ImportableKind = Exclude<
+  DefinitionKind,
+  "instructions" | "eval" | "reminder"
+>;
+
+/** The module files of a slot directory whose filenames are valid names. */
+export async function moduleEntries(
+  ctx: DiscoveryContext,
+  dir: string,
+  kind: "tool" | "connection"
+): Promise<Array<{ name: string; path: string }>> {
+  if (!(await isDirectory(dir))) {
+    return [];
+  }
+  const entries: Array<{ name: string; path: string }> = [];
+  for (const entry of await sortedEntries(dir)) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      ctx.diagnostics.push({
+        severity: "warning",
+        path: displayPath(ctx, path),
+        message: `Nested ${kind} directories are not supported; ignoring.`,
+      });
+      continue;
+    }
+    if (!entry.isFile() || !isModuleFile(entry.name)) {
+      continue;
+    }
+    const name = moduleStem(entry.name);
+    if (validateName(ctx, kind, name, path)) {
+      entries.push({ name, path });
+    }
+  }
+  return entries;
+}
+
+/**
+ * The module's default export when it carries one of the expected brands;
+ * a diagnostic and `undefined` otherwise.
+ */
+export async function importDefault(
+  ctx: DiscoveryContext,
+  modulePath: string,
+  expected: ImportableKind | readonly ImportableKind[]
+): Promise<unknown> {
+  let mod: Record<string, unknown>;
+  try {
+    mod = await ctx.importModule(modulePath);
+  } catch (error) {
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, modulePath),
+      message: `Failed to load module: ${errorMessage(error)}`,
+    });
+    return undefined;
+  }
+  const kinds = typeof expected === "string" ? [expected] : expected;
+  const kind = getDefinitionKind(mod.default);
+  if (kind !== undefined && kinds.includes(kind as ImportableKind)) {
+    return mod.default;
+  }
+  const helpers = kinds.map(helperCall).join(" or ");
+  ctx.diagnostics.push({
+    severity: "error",
+    path: displayPath(ctx, modulePath),
+    message:
+      kind === undefined
+        ? `Module must default-export ${helpers}.`
+        : `Expected a ${kinds.join(" or ")} definition but found "${kind}" (wrong authored slot?).`,
+  });
+  return undefined;
+}
+
+/** How a definition of `kind` is authored: `defineTool({ ... })`, `disableTool()`. */
+export function helperCall(kind: ImportableKind): string {
+  const name = DEFINE_HELPER_NAME[kind];
+  return kind.startsWith("disabled-") ? `${name}()` : `${name}({ ... })`;
+}
+
+const DEFINE_HELPER_NAME: Record<ImportableKind, string> = {
+  agent: "defineAgent",
+  tool: "defineTool",
+  skill: "defineSkill",
+  extension: "defineExtension",
+  "disabled-tool": "disableTool",
+  "disabled-connection": "disableConnection",
+  connection: "defineConnection",
+  channel: "defineChannel",
+  "http-channel": "httpChannel",
+  schedule: "defineSchedule",
+  hook: "defineHook",
+  ab: "defineAB",
+  storage: "defineStorage",
+  artifacts: "defineArtifacts",
+  otel: "defineOtel",
+};

package/src/internal/discovery/names.ts

@@ -0,0 +1,44 @@
+/**
+ * The path-derived naming rule: filenames become the names the model sees.
+ */
+
+import { type DiscoveryContext, displayPath } from "./context.js";
+
+export const NAME_PATTERN: RegExp = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+
+/**
+ * Filenames become the names the model sees. `__` is reserved: it joins an
+ * extension's namespace to its contribution (`ci__failed_jobs`), so no
+ * authored name may carry it.
+ */
+export function validateName(
+  ctx: DiscoveryContext,
+  kind: "skill" | "tool" | "extension" | "connection" | "subagent",
+  name: string,
+  entryPath: string
+): boolean {
+  const label = {
+    skill: "Skill",
+    tool: "Tool",
+    extension: "Extension",
+    connection: "MCP connection",
+    subagent: "Subagent",
+  }[kind];
+  if (!NAME_PATTERN.test(name)) {
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, entryPath),
+      message: `${label} name "${name}" must match ${NAME_PATTERN}.`,
+    });
+    return false;
+  }
+  if (name.includes("__")) {
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, entryPath),
+      message: `${label} name "${name}" may not contain "__"; it is reserved for extension contributions (\`<ns>__<name>\`).`,
+    });
+    return false;
+  }
+  return true;
+}

package/src/internal/discovery/project.ts

@@ -0,0 +1,270 @@
+/**
+ * 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, Diagnostic } from "../../types.js";
+import { registerAuthoredModuleLoaders } from "../authored-loaders.js";
+import { applyAgentContinuationDefaults } 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,
+  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,
+  loadStorage,
+} 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. */
+export 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 = await loadAgent(ctx, agentDir, {
+    name,
+    isRoot: true,
+  });
+
+  const { channels, httpChannelDefinition } = await loadChannels(
+    ctx,
+    join(agentDir, "channels")
+  );
+  const schedules = await loadSchedules(ctx, join(agentDir, "schedules"));
+  const hooks = await loadHooks(ctx, join(agentDir, "hooks"));
+  const abs = await loadABs(ctx, agentDir);
+  const abConfig = await loadABConfig(ctx, agentDir);
+  const storage = await loadStorage(ctx, agentDir, agent.architecture);
+  const artifacts = await loadArtifacts(ctx, agentDir);
+  const otel = await loadOtel(ctx, agentDir);
+  await appendArtifactTool(ctx, agentDir, agent, artifacts);
+
+  if (agentDir !== rootDir) {
+    await warnUnknownSlots(ctx, agentDir);
+  }
+
+  const resolvedHttpChannel = httpChannelDefinition ?? httpChannel();
+  applyAgentContinuationDefaults({
+    agent,
+    channels,
+    httpChannel: resolvedHttpChannel,
+  });
+
+  return {
+    rootDir,
+    agentDir,
+    name: agent.name,
+    agent,
+    httpChannel: resolvedHttpChannel,
+    channels,
+    schedules,
+    hooks,
+    abs,
+    abConfig,
+    storage,
+    artifacts,
+    otel,
+    diagnostics,
+  };
+}
+
+/** 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,159 @@
+/**
+ * Runtime resolution and the limitations each runtime imposes on the authored surface.
+ */
+
+import { join } from "node:path";
+import type { AgentRuntime } from "../../types.js";
+import { builtinTools } from "../builtin-tools/index.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 apply to the local session workspace only; cloud agents use the configured cloud repos.",
+    });
+  }
+}