@cursor/july 0.1.1

package/src/internal/discovery.ts

@@ -0,0 +1,1709 @@
+/**
+ * Filesystem discovery: walks a project's `agent/` directory and compiles
+ * the authored files (markdown and TypeScript) into an {@link AgentProject}
+ * manifest. Identity comes from the path — a tool at `agent/tools/foo.ts`
+ * is named `foo`, a subagent at `agent/subagents/researcher/` is named
+ * `researcher` — so no definition carries a `name` field.
+ */
+
+import type { Dirent } from "node:fs";
+import { readdir, readFile, stat } from "node:fs/promises";
+import {
+  basename,
+  extname,
+  isAbsolute,
+  join,
+  relative,
+  resolve,
+} from "node:path";
+import { pathToFileURL } from "node:url";
+import { type ABConfigFile, resolveABMaxPlaygroundSessions } from "../ab.js";
+import { httpChannel } from "../channels.js";
+import {
+  type AgentConfigDefinition,
+  type AgentProject,
+  type AgentProjectInfo,
+  type ChannelDefinition,
+  type ConnectionDefinition,
+  type ConnectionTransport,
+  DEFAULT_MODEL,
+  type Diagnostic,
+  type DiscoveredAB,
+  type DiscoveredChannel,
+  type DiscoveredConnection,
+  type DiscoveredHook,
+  type DiscoveredSchedule,
+  type DiscoveredSkill,
+  type DiscoveredTool,
+  type HookDefinition,
+  type HttpChannelDefinition,
+  type InstructionsDefinition,
+  type ModelSetting,
+  type ResolvedAgent,
+  type ScheduleDefinition,
+  type SeedFile,
+  type SkillDefinition,
+  type SkillFileSource,
+  type ToolDefinition,
+  toPublicCloudInfo,
+} from "../types.js";
+import { registerAuthoredModuleLoaders } from "./authored-loaders.js";
+import { getDefinitionKind } from "./brand.js";
+import { isValidCron } from "./cron.js";
+import { parseFrontmatter } from "./frontmatter.js";
+import { toolInputJsonSchema } from "./json-schema.js";
+import { MCP_ENDPOINT_PATH, mcpEndpointToolNames } from "./mcp-endpoint.js";
+
+const MODULE_EXTENSIONS = new Set([".ts", ".mts", ".js", ".mjs"]);
+const NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+const SKILL_DESCRIPTION_FALLBACK = (name: string): string =>
+  `Instructions for the ${name} skill.`;
+
+export interface LoadAgentProjectOptions {
+  /** Override the module loader (embedders / tests). */
+  importModule?: (absolutePath: string) => Promise<Record<string, unknown>>;
+}
+
+type ImportModule = (absolutePath: string) => Promise<Record<string, unknown>>;
+
+async function defaultImportModule(
+  absolutePath: string
+): Promise<Record<string, unknown>> {
+  return (await import(pathToFileURL(absolutePath).href)) as Record<
+    string,
+    unknown
+  >;
+}
+
+interface DiscoveryContext {
+  rootDir: string;
+  diagnostics: Diagnostic[];
+  importModule: ImportModule;
+}
+
+/**
+ * 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);
+}
+
+/**
+ * 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 results: Array<{ slug: string; project: AgentProject }> = [];
+  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, project: await loadAgentProject(childDir, options) });
+  }
+
+  if (results.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).`
+    );
+  }
+  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);
+
+  if (agentDir !== rootDir) {
+    await warnUnknownSlots(ctx, agentDir);
+  }
+
+  return {
+    rootDir,
+    agentDir,
+    name: agent.name,
+    agent,
+    httpChannel: httpChannelDefinition ?? httpChannel(),
+    channels,
+    schedules,
+    hooks,
+    abs,
+    ...(abConfig === undefined ? {} : { abConfig }),
+    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");
+}
+
+// ============================================================================
+// Agents (root + subagents)
+// ============================================================================
+
+async function loadAgent(
+  ctx: DiscoveryContext,
+  agentDir: string,
+  options: { name: string; isRoot: boolean }
+): Promise<ResolvedAgent> {
+  const config = await loadAgentConfig(ctx, agentDir, options.isRoot);
+  const instructions = await loadInstructions(
+    ctx,
+    agentDir,
+    config,
+    options.isRoot
+  );
+
+  // Subagents run as Cursor SDK custom subagents (prompt + description +
+  // model); their other slots are inert today, so don't load them — just
+  // warn that they exist.
+  if (!options.isRoot) {
+    await warnUnsupportedSubagentSlots(ctx, agentDir);
+    return {
+      name: config?.name ?? options.name,
+      ...(config?.description === undefined
+        ? {}
+        : { description: config.description }),
+      ...(config?.model === undefined ? {} : { model: config.model }),
+      ...(instructions === undefined ? {} : { instructions }),
+      runtime: "local",
+      tools: [],
+      skills: [],
+      connections: [],
+      subagents: [],
+      seedFiles: [],
+    };
+  }
+
+  const tools = await loadTools(ctx, join(agentDir, "tools"));
+  const skills = await loadSkills(ctx, join(agentDir, "skills"));
+  const connections = await loadConnections(
+    ctx,
+    await resolveMcpConnectionsDir(ctx, agentDir)
+  );
+  const seedFiles = await loadSeedFiles(ctx, agentDir);
+  const subagents = await loadSubagents(ctx, join(agentDir, "subagents"));
+  const runtime = config?.runtime === "cloud" ? "cloud" : "local";
+  // Keep authored `cloud` even when default runtime is local — per-session
+  // `send({ cloud })` merges it under cloudOverride for handoff sessions.
+  const cloud = config?.cloud;
+  const localCwd = resolveAgentCwd(ctx, config?.local?.cwd);
+  const local =
+    localCwd === undefined
+      ? undefined
+      : {
+          cwd: localCwd,
+        };
+
+  if (runtime === "cloud") {
+    warnCloudRuntimeLimitations(ctx, agentDir, {
+      serverTools: tools.filter((tool) => tool.execution === "server").length,
+      agentTools: tools.filter((tool) => tool.execution === "agent").length,
+      skills: skills.length,
+      seedFiles: seedFiles.length,
+      hasCloudOptions: cloud !== undefined,
+    });
+  }
+
+  return {
+    name: config?.name ?? options.name,
+    description: config?.description,
+    // Root agents always get a concrete model: authored value or DEFAULT_MODEL.
+    model: isValidModelSetting(config?.model) ? config.model : DEFAULT_MODEL,
+    instructions,
+    runtime,
+    cloud,
+    local,
+    tools,
+    skills,
+    connections,
+    subagents,
+    seedFiles,
+  };
+}
+
+/** Absolute harness cwd parent, or undefined when unset / blank. */
+function resolveAgentCwd(
+  ctx: DiscoveryContext,
+  authored: string | undefined
+): string | undefined {
+  if (authored === undefined) {
+    return undefined;
+  }
+  const trimmed = authored.trim();
+  if (trimmed === "") {
+    return undefined;
+  }
+  return isAbsolute(trimmed) ? trimmed : resolve(ctx.rootDir, trimmed);
+}
+
+async function loadAgentConfig(
+  ctx: DiscoveryContext,
+  agentDir: string,
+  isRoot: boolean
+): Promise<AgentConfigDefinition | undefined> {
+  const configPath = await findModuleFile(agentDir, "agent");
+  if (configPath === undefined) {
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, join(agentDir, "agent.ts")),
+      message: isRoot
+        ? "agent.ts is required on the root agent: default-export defineAgent({ ... })"
+        : "agent.ts is required on a subagent: default-export defineAgent({ description: ... })",
+    });
+    return undefined;
+  }
+
+  const definition = await importDefault(ctx, configPath, "agent");
+  if (definition === undefined) {
+    return undefined;
+  }
+  const config = definition as AgentConfigDefinition;
+
+  if (!isRoot && isBlank(config.description)) {
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, configPath),
+      message:
+        "Subagents require a description; the parent model reads it to decide when to delegate.",
+    });
+  }
+  return config;
+}
+
+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;
+}
+
+// ============================================================================
+// Tools
+// ============================================================================
+
+async function loadTools(
+  ctx: DiscoveryContext,
+  toolsDir: string
+): Promise<DiscoveredTool[]> {
+  if (!(await isDirectory(toolsDir))) {
+    return [];
+  }
+  const tools: DiscoveredTool[] = [];
+  for (const entry of await sortedEntries(toolsDir)) {
+    const entryPath = join(toolsDir, entry.name);
+    if (entry.isDirectory()) {
+      ctx.diagnostics.push({
+        severity: "warning",
+        path: displayPath(ctx, entryPath),
+        message: "Nested tool directories are not supported; ignoring.",
+      });
+      continue;
+    }
+    if (!entry.isFile() || !isModuleFile(entry.name)) {
+      continue;
+    }
+    const name = moduleStem(entry.name);
+    if (!NAME_PATTERN.test(name)) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, entryPath),
+        message: `Tool name "${name}" must match ${NAME_PATTERN} (the filename becomes the tool name the model sees).`,
+      });
+      continue;
+    }
+    const definition = await importDefault(ctx, entryPath, "tool");
+    if (definition === undefined) {
+      continue;
+    }
+    const tool = definition as ToolDefinition;
+    if (isBlank(tool.description)) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, entryPath),
+        message: "Tools require a non-empty description.",
+      });
+      continue;
+    }
+    const execution = tool.execution === "agent" ? "agent" : "server";
+    const needsApprovalConfigured =
+      tool.needsApproval === true || typeof tool.needsApproval === "function";
+    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).',
+        });
+        continue;
+      }
+      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).',
+        });
+        continue;
+      }
+    } 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).',
+      });
+      continue;
+    }
+    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)}`,
+      });
+      continue;
+    }
+    tools.push({
+      name,
+      description: tool.description,
+      inputSchema,
+      execution,
+      needsApproval: needsApprovalConfigured,
+      ...(execution === "agent" && tool.script !== undefined
+        ? { script: tool.script }
+        : {}),
+      definition: tool,
+    });
+  }
+  return tools;
+}
+
+// ============================================================================
+// Skills
+// ============================================================================
+
+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 (!validateSkillName(ctx, name, entryPath)) {
+        continue;
+      }
+      const { data, body } = parseFrontmatter(
+        await readFile(entryPath, "utf8")
+      );
+      skills.push({
+        name,
+        description:
+          data.description ??
+          deriveSkillDescription(body) ??
+          SKILL_DESCRIPTION_FALLBACK(name),
+        markdown: body.trim(),
+        files: {},
+      });
+      continue;
+    }
+    if (isModuleFile(entry.name)) {
+      const name = moduleStem(entry.name);
+      if (!validateSkillName(ctx, name, entryPath)) {
+        continue;
+      }
+      const definition = await importDefault(ctx, entryPath, "skill");
+      if (definition === undefined) {
+        continue;
+      }
+      const skill = definition as SkillDefinition;
+      const files: Record<string, SkillFileSource> = {};
+      for (const [rel, contents] of Object.entries(skill.files ?? {})) {
+        files[rel] = { contents };
+      }
+      skills.push({
+        name,
+        description:
+          skill.description ??
+          deriveSkillDescription(skill.markdown) ??
+          SKILL_DESCRIPTION_FALLBACK(name),
+        markdown: skill.markdown.trim(),
+        files,
+      });
+    }
+  }
+  return skills;
+}
+
+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 (!validateSkillName(ctx, 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;
+  }
+
+  const files: Record<string, SkillFileSource> = {};
+  for (const filePath of await walkFiles(skillDir)) {
+    const rel = toPosix(relative(skillDir, filePath));
+    if (rel === "SKILL.md") {
+      continue;
+    }
+    files[rel] = { sourcePath: filePath };
+  }
+
+  return {
+    name,
+    description: data.description,
+    markdown: body.trim(),
+    files,
+  };
+}
+
+/** One-line `/v1/info` label for a connection transport. */
+function connectionTransportLabel(transport: ConnectionTransport): string {
+  if ("cursorAccount" in transport) {
+    return transport.servers === undefined
+      ? "cursor-account"
+      : `cursor-account:${transport.servers.join(",")}`;
+  }
+  if ("agent" in transport) {
+    return `agent:${transport.agent}`;
+  }
+  if ("url" in transport) {
+    return transport.url;
+  }
+  return transport.command;
+}
+
+function connectionTransport(
+  connection: ConnectionDefinition
+): ConnectionTransport | undefined {
+  if ("cursorAccount" in connection && connection.cursorAccount === true) {
+    return {
+      cursorAccount: true,
+      ...(connection.servers === undefined
+        ? {}
+        : { servers: connection.servers }),
+    };
+  }
+  if ("agent" in connection && !isBlank(connection.agent)) {
+    return { agent: connection.agent };
+  }
+  if ("url" in connection && !isBlank(connection.url)) {
+    return {
+      ...(connection.type === undefined ? {} : { type: connection.type }),
+      url: connection.url,
+      ...(connection.headers === undefined
+        ? {}
+        : { headers: connection.headers }),
+    };
+  }
+  if ("command" in connection && !isBlank(connection.command)) {
+    return {
+      ...(connection.type === undefined ? {} : { type: connection.type }),
+      command: connection.command,
+      ...(connection.args === undefined ? {} : { args: connection.args }),
+      ...(connection.env === undefined ? {} : { env: connection.env }),
+      ...(connection.cwd === undefined ? {} : { cwd: connection.cwd }),
+    };
+  }
+  return undefined;
+}
+
+function validateSkillName(
+  ctx: DiscoveryContext,
+  name: string,
+  entryPath: string
+): boolean {
+  if (NAME_PATTERN.test(name)) {
+    return true;
+  }
+  ctx.diagnostics.push({
+    severity: "error",
+    path: displayPath(ctx, entryPath),
+    message: `Skill name "${name}" must match ${NAME_PATTERN}.`,
+  });
+  return false;
+}
+
+/**
+ * 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;
+}
+
+// ============================================================================
+// MCP connections
+// ============================================================================
+
+/**
+ * Prefer `agent/mcp-connections/`. Keep loading `agent/connections/` with a
+ * deprecation warning so existing agents keep working during the rename.
+ */
+async function resolveMcpConnectionsDir(
+  ctx: DiscoveryContext,
+  agentDir: string
+): Promise<string> {
+  const preferred = join(agentDir, "mcp-connections");
+  const legacy = join(agentDir, "connections");
+  const hasPreferred = await isDirectory(preferred);
+  const hasLegacy = await isDirectory(legacy);
+  if (hasPreferred && hasLegacy) {
+    ctx.diagnostics.push({
+      severity: "warning",
+      path: displayPath(ctx, legacy),
+      message:
+        "Both agent/mcp-connections/ and agent/connections/ exist; using mcp-connections/ and ignoring connections/. Rename or remove the legacy directory.",
+    });
+    return preferred;
+  }
+  if (hasLegacy) {
+    ctx.diagnostics.push({
+      severity: "warning",
+      path: displayPath(ctx, legacy),
+      message:
+        "agent/connections/ is deprecated; rename it to agent/mcp-connections/. Loading from the legacy path for now.",
+    });
+    return legacy;
+  }
+  return preferred;
+}
+
+async function loadConnections(
+  ctx: DiscoveryContext,
+  connectionsDir: string
+): Promise<DiscoveredConnection[]> {
+  if (!(await isDirectory(connectionsDir))) {
+    return [];
+  }
+  const connections: DiscoveredConnection[] = [];
+  for (const entry of await sortedEntries(connectionsDir)) {
+    const entryPath = join(connectionsDir, entry.name);
+    if (!entry.isFile() || !isModuleFile(entry.name)) {
+      continue;
+    }
+    const name = moduleStem(entry.name);
+    if (!NAME_PATTERN.test(name)) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, entryPath),
+        message: `MCP connection name "${name}" must match ${NAME_PATTERN}.`,
+      });
+      continue;
+    }
+    const definition = await importDefault(ctx, entryPath, "connection");
+    if (definition === undefined) {
+      continue;
+    }
+    const connection = definition as ConnectionDefinition;
+    const transport = connectionTransport(connection);
+    if (transport === undefined) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, entryPath),
+        message:
+          "MCP connections require a `url` (http/sse), a `command` (stdio), an `agent` (peer agent slug on the same serve host), or `cursorAccount: true` (the Cursor account's MCP connectors).",
+      });
+      continue;
+    }
+    if (
+      "cursorAccount" in transport &&
+      transport.servers !== undefined &&
+      (transport.servers.length === 0 ||
+        transport.servers.some((server) => isBlank(server)))
+    ) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, entryPath),
+        message:
+          "Cursor account MCP connection `servers` must be a non-empty list of connector names (or omitted to expose every connected server).",
+      });
+      continue;
+    }
+    if ("agent" in transport && !NAME_PATTERN.test(transport.agent)) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, entryPath),
+        message: `Peer MCP connection agent "${transport.agent}" must be a mount slug matching ${NAME_PATTERN}.`,
+      });
+      continue;
+    }
+    connections.push({
+      name,
+      transport,
+      ...(connection.description === undefined
+        ? {}
+        : { description: connection.description }),
+    });
+  }
+  return connections;
+}
+
+// ============================================================================
+// Subagents
+// ============================================================================
+
+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 (!NAME_PATTERN.test(entry.name)) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, subagentDir),
+        message: `Subagent name "${entry.name}" must match ${NAME_PATTERN}.`,
+      });
+      continue;
+    }
+    subagents.push(
+      await loadAgent(ctx, subagentDir, { name: entry.name, isRoot: false })
+    );
+  }
+  return subagents;
+}
+
+async function warnUnsupportedSubagentSlots(
+  ctx: DiscoveryContext,
+  subagentDir: string
+): Promise<void> {
+  const unsupported = [
+    ["tools", "tools"],
+    ["skills", "skills"],
+    ["mcp-connections", "MCP connections"],
+    ["connections", "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.`,
+      });
+    }
+  }
+}
+
+function warnCloudRuntimeLimitations(
+  ctx: DiscoveryContext,
+  agentDir: string,
+  counts: {
+    serverTools: number;
+    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.serverTools > 0) {
+    ctx.diagnostics.push({
+      severity: "warning",
+      path: displayPath(ctx, join(agentDir, "tools")),
+      message:
+        'In-process tools (execution: "server", the default) are not available on cloud agents. Use execution: "agent", MCP connections, or tools that already live in the cloud workspace.',
+    });
+  }
+  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 are materialized into the local session workspace only; cloud agents see skills that already exist in the cloud repo.",
+    });
+  }
+  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.",
+    });
+  }
+}
+
+// ============================================================================
+// Channels
+// ============================================================================
+
+async function loadChannels(
+  ctx: DiscoveryContext,
+  channelsDir: string
+): Promise<{
+  channels: DiscoveredChannel[];
+  httpChannelDefinition: HttpChannelDefinition | undefined;
+}> {
+  const channels: DiscoveredChannel[] = [];
+  let httpChannelDefinition: HttpChannelDefinition | undefined;
+  if (!(await isDirectory(channelsDir))) {
+    return { channels, httpChannelDefinition };
+  }
+
+  for (const entry of await sortedEntries(channelsDir)) {
+    const entryPath = join(channelsDir, entry.name);
+    if (!entry.isFile() || !isModuleFile(entry.name)) {
+      continue;
+    }
+    const id = moduleStem(entry.name);
+    if (!NAME_PATTERN.test(id)) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, entryPath),
+        message: `Channel id "${id}" must match ${NAME_PATTERN}.`,
+      });
+      continue;
+    }
+
+    let mod: Record<string, unknown>;
+    try {
+      mod = await ctx.importModule(entryPath);
+    } catch (error) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, entryPath),
+        message: `Failed to load module: ${errorMessage(error)}`,
+      });
+      continue;
+    }
+    const kind = getDefinitionKind(mod.default);
+
+    if (kind === "http-channel") {
+      if (id !== "http") {
+        ctx.diagnostics.push({
+          severity: "error",
+          path: displayPath(ctx, entryPath),
+          message:
+            "httpChannel() configures the built-in HTTP channel and must be authored at channels/http.ts.",
+        });
+        continue;
+      }
+      httpChannelDefinition = mod.default as HttpChannelDefinition;
+      continue;
+    }
+
+    if (kind !== "channel") {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, entryPath),
+        message:
+          id === "http"
+            ? "channels/http.ts must default-export httpChannel({ ... })."
+            : "Channel modules must default-export defineChannel({ ... }).",
+      });
+      continue;
+    }
+    if (id === "http") {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, entryPath),
+        message:
+          "The channel id `http` is reserved for the built-in HTTP channel; use httpChannel() to configure it.",
+      });
+      continue;
+    }
+    channels.push({ id, definition: mod.default as ChannelDefinition });
+  }
+  return { channels, httpChannelDefinition };
+}
+
+// ============================================================================
+// Schedules
+// ============================================================================
+
+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;
+}
+
+// ============================================================================
+// Hooks
+// ============================================================================
+
+async function loadHooks(
+  ctx: DiscoveryContext,
+  hooksDir: string
+): Promise<DiscoveredHook[]> {
+  if (!(await isDirectory(hooksDir))) {
+    return [];
+  }
+  const hooks: DiscoveredHook[] = [];
+  for (const filePath of await walkFiles(hooksDir)) {
+    if (!isModuleFile(basename(filePath))) {
+      continue;
+    }
+    const rel = toPosix(relative(hooksDir, filePath));
+    const name = rel.slice(0, -extname(rel).length);
+    const definition = await importDefault(ctx, filePath, "hook");
+    if (definition === undefined) {
+      continue;
+    }
+    const hook = definition as HookDefinition;
+    if (
+      typeof hook.events !== "object" ||
+      hook.events === null ||
+      Object.keys(hook.events).length === 0
+    ) {
+      ctx.diagnostics.push({
+        severity: "warning",
+        path: displayPath(ctx, filePath),
+        message: "Hook declares no event handlers.",
+      });
+      continue;
+    }
+    hooks.push({ name, definition: hook });
+  }
+  return hooks;
+}
+
+// ============================================================================
+// A/B metrics (agent/ab.ts or agent/ab/*.ts) + agent/ab.config.ts
+// ============================================================================
+
+async function loadABs(
+  ctx: DiscoveryContext,
+  agentDir: string
+): Promise<DiscoveredAB[]> {
+  const abs: DiscoveredAB[] = [];
+  const seen = new Set<string>();
+
+  const single = await findModuleFile(agentDir, "ab");
+  if (single !== undefined) {
+    const definition = await importDefault(ctx, single, "ab");
+    if (definition !== undefined) {
+      const name = resolveABName(definition, "ab");
+      seen.add(name);
+      abs.push({
+        name,
+        definition: definition as DiscoveredAB["definition"],
+      });
+    }
+  }
+
+  const absDir = join(agentDir, "ab");
+  if (await isDirectory(absDir)) {
+    for (const filePath of await walkFiles(absDir)) {
+      if (!isModuleFile(basename(filePath))) {
+        continue;
+      }
+      const rel = toPosix(relative(absDir, filePath));
+      const stem = rel.slice(0, -extname(rel).length);
+      const definition = await importDefault(ctx, filePath, "ab");
+      if (definition === undefined) {
+        continue;
+      }
+      const name = resolveABName(definition, stem);
+      if (seen.has(name)) {
+        ctx.diagnostics.push({
+          severity: "error",
+          path: displayPath(ctx, filePath),
+          message: `Duplicate A/B experiment name ${JSON.stringify(name)}.`,
+        });
+        continue;
+      }
+      seen.add(name);
+      abs.push({
+        name,
+        definition: definition as DiscoveredAB["definition"],
+      });
+    }
+  }
+
+  return abs;
+}
+
+async function loadABConfig(
+  ctx: DiscoveryContext,
+  agentDir: string
+): Promise<ABConfigFile | undefined> {
+  const path = await findModuleFile(agentDir, "ab.config");
+  if (path === undefined) {
+    return undefined;
+  }
+  try {
+    const mod = await ctx.importModule(path);
+    if (mod.default === null || typeof mod.default !== "object") {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, path),
+        message:
+          "ab.config.ts must default-export defineABConfig({ ... }) from @anysphere/agent-serve/ab.",
+      });
+      return undefined;
+    }
+    return mod.default as ABConfigFile;
+  } catch (error) {
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, path),
+      message: `Failed to load ab.config: ${error instanceof Error ? error.message : String(error)}`,
+    });
+    return undefined;
+  }
+}
+
+function resolveABName(definition: unknown, fallback: string): string {
+  if (
+    typeof definition === "object" &&
+    definition !== null &&
+    "name" in definition &&
+    typeof (definition as { name: unknown }).name === "string" &&
+    (definition as { name: string }).name.length > 0
+  ) {
+    return (definition as { name: string }).name;
+  }
+  return fallback;
+}
+
+// ============================================================================
+// Sandbox seed files
+// ============================================================================
+
+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;
+}
+
+// ============================================================================
+// Info projection
+// ============================================================================
+
+export function projectInfo(project: AgentProject): AgentProjectInfo {
+  const agent = project.agent;
+  const httpRoutes: AgentProjectInfo["channels"][number]["routes"] = [
+    { method: "POST", path: "/v1/session", url: "/v1/session" },
+    {
+      method: "POST",
+      path: "/v1/session/:sessionId",
+      url: "/v1/session/:sessionId",
+    },
+    {
+      method: "POST",
+      path: "/v1/session/:sessionId/stop",
+      url: "/v1/session/:sessionId/stop",
+    },
+    {
+      method: "GET",
+      path: "/v1/session/:sessionId/stream",
+      url: "/v1/session/:sessionId/stream",
+    },
+    {
+      method: "GET",
+      path: "/v1/session/:sessionId/approvals",
+      url: "/v1/session/:sessionId/approvals",
+    },
+    {
+      method: "POST",
+      path: "/v1/session/:sessionId/approvals/:callId",
+      url: "/v1/session/:sessionId/approvals/:callId",
+    },
+  ];
+  return {
+    name: project.name,
+    model: agent.model,
+    runtime: agent.runtime,
+    cloud:
+      agent.cloud === undefined ? undefined : toPublicCloudInfo(agent.cloud),
+    local: agent.local,
+    mcp: { path: MCP_ENDPOINT_PATH, tools: mcpEndpointToolNames(project) },
+    instructions:
+      agent.instructions === undefined
+        ? undefined
+        : {
+            chars: agent.instructions.length,
+            preview:
+              agent.instructions.length > 280
+                ? `${agent.instructions.slice(0, 277)}...`
+                : agent.instructions,
+          },
+    tools: agent.tools.map((tool) => ({
+      name: tool.name,
+      description: tool.description,
+      execution: tool.execution,
+      needsApproval: tool.needsApproval,
+      inputSchema: tool.inputSchema,
+    })),
+    skills: agent.skills.map((skill) => ({
+      name: skill.name,
+      description: skill.description,
+    })),
+    connections: agent.connections.map((connection) => ({
+      name: connection.name,
+      transport: connectionTransportLabel(connection.transport),
+    })),
+    subagents: agent.subagents.map((subagent) => ({
+      name: subagent.name,
+      description: subagent.description,
+      model: subagent.model,
+    })),
+    channels: [
+      { id: "http", routes: httpRoutes },
+      ...project.channels.map((channel) => {
+        const info: AgentProjectInfo["channels"][number] = {
+          id: channel.id,
+          routes: (channel.definition.routes ?? []).map((r) => {
+            const routeInfo: AgentProjectInfo["channels"][number]["routes"][number] =
+              {
+                method: r.method,
+                path: r.path,
+                url: `/v1/channels/${channel.id}${r.path}`,
+              };
+            if (r.description !== undefined) {
+              routeInfo.description = r.description;
+            }
+            if (r.bodySchema !== undefined) {
+              routeInfo.bodySchema = toolInputJsonSchema(r.bodySchema);
+            }
+            if (r.querySchema !== undefined) {
+              routeInfo.querySchema = toolInputJsonSchema(r.querySchema);
+            }
+            return routeInfo;
+          }),
+        };
+        const meta = channel.definition.meta;
+        if (meta?.kind !== undefined) {
+          info.kind = meta.kind;
+        }
+        if (meta?.githubWebhookEvents !== undefined) {
+          info.githubWebhookEvents = meta.githubWebhookEvents;
+        }
+        if (meta?.slackChannelPosts !== undefined) {
+          info.slackChannelPosts = meta.slackChannelPosts;
+        }
+        return info;
+      }),
+    ],
+    schedules: project.schedules.map((schedule) => ({
+      name: schedule.name,
+      cron: schedule.cron,
+      kind: schedule.kind,
+    })),
+    hooks: project.hooks.map((hook) => hook.name),
+    abs: project.abs.map((experiment) => experiment.name),
+    ...(project.abConfig === undefined && project.abs.length === 0
+      ? {}
+      : {
+          abConfig: {
+            maxPlaygroundSessions: resolveABMaxPlaygroundSessions(
+              project.abConfig?.maxPlaygroundSessions
+            ),
+            durableSamples: project.abConfig?.persistSamples !== undefined,
+            durableSnapshots: project.abConfig?.persistSnapshots !== undefined,
+          },
+        }),
+    diagnostics: project.diagnostics,
+  };
+}
+
+// ============================================================================
+// Shared helpers
+// ============================================================================
+
+async function importDefault(
+  ctx: DiscoveryContext,
+  modulePath: string,
+  expectedKind:
+    | "agent"
+    | "tool"
+    | "skill"
+    | "connection"
+    | "schedule"
+    | "hook"
+    | "ab"
+): 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 kind = getDefinitionKind(mod.default);
+  if (kind !== expectedKind) {
+    const helper =
+      expectedKind === "ab"
+        ? "defineAB"
+        : `define${expectedKind[0]?.toUpperCase()}${expectedKind.slice(1)}`;
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, modulePath),
+      message:
+        kind === undefined
+          ? `Module must default-export ${helper}({ ... }).`
+          : `Expected a ${expectedKind} definition but found "${kind}" (wrong authored slot?).`,
+    });
+    return undefined;
+  }
+  return mod.default;
+}
+
+async function warnUnknownSlots(
+  ctx: DiscoveryContext,
+  agentDir: string
+): Promise<void> {
+  const known = new Set([
+    "agent",
+    "instructions",
+    "tools",
+    "skills",
+    "mcp-connections",
+    // Legacy slot name; resolveMcpConnectionsDir warns and still loads it.
+    "connections",
+    "subagents",
+    "channels",
+    "schedules",
+    "hooks",
+    "ab",
+    "sandbox",
+    "lib",
+    // Vite playground custom tool chips (examples/*/agent/playground/tools).
+    "playground",
+  ]);
+  for (const entry of await sortedEntries(agentDir)) {
+    if (!entry.isDirectory() || entry.name.startsWith(".")) {
+      continue;
+    }
+    if (entry.name === "node_modules" || known.has(entry.name)) {
+      continue;
+    }
+    // Footgun: evals live at project-root `evals/`, not under `agent/`.
+    if (entry.name === "evals") {
+      ctx.diagnostics.push({
+        severity: "warning",
+        path: displayPath(ctx, join(agentDir, entry.name)),
+        message:
+          'Directory "evals" under agent/ is ignored — put defineEval files at project-root evals/ instead.',
+      });
+      continue;
+    }
+    ctx.diagnostics.push({
+      severity: "warning",
+      path: displayPath(ctx, join(agentDir, entry.name)),
+      message: `Unrecognized directory "${entry.name}" under agent/ (not an authored slot; use lib/ for shared code).`,
+    });
+  }
+}
+
+async function hasFlatLayoutMarkers(rootDir: string): Promise<boolean> {
+  if (await isFile(join(rootDir, "instructions.md"))) {
+    return true;
+  }
+  return (await findModuleFile(rootDir, "agent")) !== undefined;
+}
+
+async function readPackageName(rootDir: string): Promise<string | undefined> {
+  const packageJsonPath = join(rootDir, "package.json");
+  if (!(await isFile(packageJsonPath))) {
+    return undefined;
+  }
+  try {
+    const parsed = JSON.parse(await readFile(packageJsonPath, "utf8")) as {
+      name?: unknown;
+    };
+    if (typeof parsed.name === "string" && parsed.name !== "") {
+      return parsed.name;
+    }
+  } catch {
+    // Malformed package.json falls back to the directory name.
+  }
+  return undefined;
+}
+
+async function findModuleFile(
+  dir: string,
+  stem: string
+): Promise<string | undefined> {
+  for (const extension of [".ts", ".mts", ".js", ".mjs"]) {
+    const candidate = join(dir, `${stem}${extension}`);
+    if (await isFile(candidate)) {
+      return candidate;
+    }
+  }
+  return undefined;
+}
+
+function isModuleFile(fileName: string): boolean {
+  if (fileName.endsWith(".d.ts") || fileName.startsWith(".")) {
+    return false;
+  }
+  return MODULE_EXTENSIONS.has(extname(fileName));
+}
+
+function moduleStem(fileName: string): string {
+  return fileName.slice(0, -extname(fileName).length);
+}
+
+async function sortedEntries(dir: string): Promise<Dirent[]> {
+  const entries = await readdir(dir, { withFileTypes: true });
+  return entries.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+async function walkFiles(dir: string): Promise<string[]> {
+  const files: string[] = [];
+  for (const entry of await sortedEntries(dir)) {
+    if (entry.name.startsWith(".")) {
+      continue;
+    }
+    const entryPath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...(await walkFiles(entryPath)));
+    } else if (entry.isFile()) {
+      files.push(entryPath);
+    }
+  }
+  return files;
+}
+
+async function isDirectory(path: string): Promise<boolean> {
+  try {
+    return (await stat(path)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+async function isFile(path: string): Promise<boolean> {
+  try {
+    return (await stat(path)).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function isValidModelSetting(model: unknown): model is ModelSetting {
+  if (typeof model === "string") {
+    return model.trim() !== "";
+  }
+  return (
+    typeof model === "object" &&
+    model !== null &&
+    typeof (model as { id?: unknown }).id === "string" &&
+    (model as { id: string }).id.trim() !== ""
+  );
+}
+
+function isBlank(value: unknown): boolean {
+  return typeof value !== "string" || value.trim() === "";
+}
+
+function toPosix(path: string): string {
+  return path.split("\\").join("/");
+}
+
+function displayPath(ctx: DiscoveryContext, absolutePath: string): string {
+  const rel = relative(ctx.rootDir, absolutePath);
+  return rel.startsWith("..") ? absolutePath : toPosix(rel);
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}