@cursor/july 0.1.101 → 0.1.102

package/src/internal/discovery.ts

@@ -4,3084 +4,23 @@
  * 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 { resolveArtifactsMax } from "../artifacts.js";
-import { httpChannel } from "../channels.js";
-import type { OtelDefinition } from "../otel.js";
-import type { StorageDefinition } from "../storage.js";
-import {
-  type AgentArchitecture,
-  type AgentConcurrencyOptions,
-  type AgentConfigDefinition,
-  type AgentHostingOptions,
-  type AgentProject,
-  type AgentProjectInfo,
-  type AgentRuntime,
-  type ArtifactsDefinition,
-  type BuiltinToolsConfig,
-  type ChannelDefinition,
-  type ConnectionDefinition,
-  type ConnectionTransport,
-  cursorAccountServersHasMixedWildcard,
-  DEFAULT_MODEL,
-  type Diagnostic,
-  type DiscoveredAB,
-  type DiscoveredChannel,
-  type DiscoveredConnection,
-  type DiscoveredExtension,
-  type DiscoveredHook,
-  type DiscoveredSchedule,
-  type DiscoveredSkill,
-  type DiscoveredTool,
-  type ExtensionMount,
-  type HookDefinition,
-  type HttpChannelDefinition,
-  type InlineStdioConnectionConfig,
-  type InstructionsDefinition,
-  isInlineStdioConnection,
-  isToolEffect,
-  MAX_RUNNING_TURNS_LIMIT,
-  type ModelSetting,
-  normalizeConnectionEffects,
-  normalizeConnectionTools,
-  normalizeCursorAccountServers,
-  type ResolvedAgent,
-  type ScheduleDefinition,
-  type SeedFile,
-  type SkillConfig,
-  type SkillDefinition,
-  type SkillFileSource,
-  type ToolDefinition,
-  type ToolEffect,
-  toPublicCloudInfo,
-} from "../types.js";
-import { registerAuthoredModuleLoaders } from "./authored-loaders.js";
-import { normalizePositiveInt } from "./bounded-int.js";
-import { getDefinitionKind } from "./brand.js";
-import {
-  artifactBuiltinTool,
-  builtinTools,
-  TAG_ARTIFACT_TOOL_NAME,
-} from "./builtin-tools/index.js";
-import { applyAgentContinuationDefaults } from "./continuation-channel.js";
-import { isValidCron } from "./cron.js";
-import { parseFrontmatter } from "./frontmatter.js";
-import {
-  isReservedSecretName,
-  MAX_EGRESS_DOMAINS,
-  validateEgressDomain,
-  validateSecretName,
-} from "./hosting.js";
-import { toolInputJsonSchema, toolOutputJsonSchema } from "./json-schema.js";
-import { MCP_ENDPOINT_PATH, mcpEndpointToolNames } from "./mcp-endpoint.js";
-import { packageInlineStdioConnection } from "./package-inline-stdio.js";
-import {
-  defaultLocalHarnessCwd,
-  isNestedInGitRepo,
-  withIdentityPreamble,
-} from "./workspace.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);
-}
-
-/** 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");
-}
-
-// ============================================================================
-// 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 name = config?.name ?? options.name;
-  const authoredInstructions = await loadInstructions(
-    ctx,
-    agentDir,
-    config,
-    options.isRoot
-  );
-  // Root agents without authored instructions stay undefined (diagnostic
-  // already recorded). Subagents still get the identity line alone.
-  const instructions =
-    authoredInstructions === undefined && options.isRoot
-      ? undefined
-      : withIdentityPreamble(name, authoredInstructions);
-
-  // 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);
-    if (config?.builtinTools !== undefined) {
-      ctx.diagnostics.push({
-        severity: "warning",
-        path: displayPath(ctx, join(agentDir, "agent.ts")),
-        message: "builtinTools is not supported on subagents; ignoring.",
-      });
-    }
-    if (config?.tools !== undefined) {
-      ctx.diagnostics.push({
-        severity: "warning",
-        path: displayPath(ctx, join(agentDir, "agent.ts")),
-        message:
-          "tools is not supported on subagents (they keep the harness task-tool toolset); ignoring.",
-      });
-    }
-    if (config?.architecture !== undefined) {
-      ctx.diagnostics.push({
-        severity: "warning",
-        path: displayPath(ctx, join(agentDir, "agent.ts")),
-        message: "architecture is not supported on subagents; ignoring.",
-      });
-    }
-    const artifactsPath = await findModuleFile(agentDir, "artifacts");
-    if (artifactsPath !== undefined) {
-      ctx.diagnostics.push({
-        severity: "warning",
-        path: displayPath(ctx, artifactsPath),
-        message: "artifacts are not supported on subagents; ignoring.",
-      });
-    }
-    return {
-      name,
-      ...(config?.description === undefined
-        ? {}
-        : { description: config.description }),
-      ...(config?.model === undefined ? {} : { model: config.model }),
-      ...(instructions === undefined ? {} : { instructions }),
-      runtime: "local",
-      tools: [],
-      skills: [],
-      connections: [],
-      hostConnections: [],
-      subagents: [],
-      seedFiles: [],
-    };
-  }
-
-  const tools = await loadTools(ctx, join(agentDir, "tools"));
-  const skills = await loadSkills(ctx, join(agentDir, "skills"));
-  const extensions = await appendExtensions(
-    ctx,
-    join(agentDir, "extensions"),
-    tools,
-    skills
-  );
-  const connections = await loadConnections(
-    ctx,
-    await resolveMcpConnectionsDir(ctx, agentDir)
-  );
-  const hostConnections = await loadHostConnections(ctx, agentDir, connections);
-  const seedFiles = await loadSeedFiles(ctx, agentDir);
-  const subagents = await loadSubagents(ctx, join(agentDir, "subagents"));
-  const runtime = resolveRuntime(ctx, agentDir, config?.runtime);
-  // 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 localWorkspaceDir = resolveAgentCwd(ctx, config?.local?.workspaceDir);
-  const localCwd = await resolveLocalCwd(
-    ctx,
-    config?.local?.cwd,
-    config?.local?.workspaceDir
-  );
-  const localSandbox = config?.local?.sandbox === true;
-  // Built-in tool allowlist (top-level `tools`). `[]` is meaningful (no
-  // native built-in tools), so presence is keyed on the field, not on
-  // emptiness. "mcp" is always granted alongside a configured allowlist:
-  // it is transport, not capability — this kit's own server tools ride the
-  // SDK custom-tool MCP path, so omitting it silently breaks
-  // `agent/tools/`, and what MCP actually exposes stays controlled by the
-  // second layer (authored tools, mcp-connections, the harness cwd's
-  // ambient config).
-  const authoredAllowlist = config?.tools;
-  const allowedTools =
-    authoredAllowlist === undefined || authoredAllowlist.includes("mcp")
-      ? authoredAllowlist
-      : [...authoredAllowlist, "mcp" as const];
-  // The allowlist states runtime-agnostic intent, but only the local
-  // harness can enforce it (the Cursor SDK rejects tool restrictions on
-  // cloud agents, and the Grok Bot harness has its own fixed toolset) — a
-  // non-local agent that declares one must fail at serve start, never run
-  // unrestricted. (Hybrid per-send cloud sessions fail closed in the
-  // session engine.)
-  if (allowedTools !== undefined && runtime !== "local") {
-    ctx.diagnostics.push({
-      severity: "error",
-      path: displayPath(ctx, join(agentDir, "agent.ts")),
-      message: `tools cannot be enforced on runtime: "${runtime}". Remove \`tools\` or run the agent on the local runtime.`,
-    });
-  }
-  // Per-session connection features (defineConnection auth/advertiseTools)
-  // only run on local turns: advertised tools are in-process server tools,
-  // and per-session headers cannot reach a cloud VM's MCP config. A
-  // non-local agent that declares them must fail at serve start — never
-  // run without the connection's tools or identity. (Hybrid per-send
-  // cloud sessions fail closed in the session engine.)
-  const perSessionConnection = connections.find(
-    (connection) =>
-      connection.advertiseTools === true || connection.auth !== undefined
-  );
-  if (perSessionConnection !== undefined && runtime !== "local") {
-    ctx.diagnostics.push({
-      severity: "error",
-      path: displayPath(ctx, join(agentDir, "agent.ts")),
-      message: `MCP connection "${perSessionConnection.name}" uses advertiseTools/auth, which only run on runtime: "local". Remove them or run the agent on the local runtime.`,
-    });
-  }
-  // `execution: "agent"` tool scripts run through the shell tool. Shell is
-  // a real capability, so it is never injected — but an allowlist that
-  // strands authored scripts deserves a loud diagnostic, not silence.
-  if (
-    allowedTools !== undefined &&
-    !allowedTools.includes("shell") &&
-    tools.some((tool) => tool.execution === "agent")
-  ) {
-    ctx.diagnostics.push({
-      severity: "warning",
-      path: displayPath(ctx, join(agentDir, "agent.ts")),
-      message:
-        '`tools` omits "shell" but this agent has execution: "agent" tools, which run as shell scripts; the model will not be able to run them.',
-    });
-  }
-  if (localCwd !== undefined && localWorkspaceDir !== undefined) {
-    ctx.diagnostics.push({
-      severity: "warning",
-      path: displayPath(ctx, join(agentDir, "agent.ts")),
-      message:
-        "local.workspaceDir pins every session to one directory, so local.cwd is unused. Drop one of them.",
-    });
-  }
-  const local =
-    localCwd === undefined && localWorkspaceDir === undefined && !localSandbox
-      ? undefined
-      : {
-          cwd: localCwd,
-          workspaceDir: localWorkspaceDir,
-          sandbox: localSandbox,
-        };
-  const hosting = resolveHosting(ctx, agentDir, config?.hosting);
-  const concurrency = resolveConcurrency(ctx, agentDir, config?.concurrency);
-  const architecture = resolveArchitecture(ctx, agentDir, config?.architecture);
-  const runtimeArchitectureError = runtimeArchitectureCompatibilityError({
-    runtime,
-    architecture,
-  });
-  if (runtimeArchitectureError !== undefined) {
-    ctx.diagnostics.push({
-      severity: "error",
-      path: displayPath(ctx, join(agentDir, "agent.ts")),
-      message: runtimeArchitectureError,
-    });
-  }
-
-  if (runtime === "cloud") {
-    warnCloudRuntimeLimitations(ctx, agentDir, {
-      agentTools: tools.filter((tool) => tool.execution === "agent").length,
-      skills: skills.length,
-      seedFiles: seedFiles.length,
-      hasCloudOptions: cloud !== undefined,
-    });
-  }
-  appendBuiltinTools(ctx, agentDir, tools, config?.builtinTools);
-
-  // After appendBuiltinTools so opted-in built-ins (server-executed) count.
-  if (runtime === "grokbot") {
-    checkGrokBotRuntimeLimitations(ctx, agentDir, {
-      serverTools: tools.filter((tool) => tool.execution === "server").length,
-      agentTools: tools.filter((tool) => tool.execution === "agent").length,
-      skills: skills.length,
-      seedFiles: seedFiles.length,
-      connections: connections.length + hostConnections.length,
-      subagents: subagents.length,
-      hasCloudOptions: cloud !== undefined,
-      hasLocalSandbox: localSandbox,
-    });
-  }
-
-  return {
-    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,
-    ...(allowedTools === undefined ? {} : { allowedTools }),
-    hosting,
-    concurrency,
-    ...(architecture === undefined ? {} : { architecture }),
-    tools,
-    skills,
-    extensions,
-    connections,
-    hostConnections,
-    subagents,
-    seedFiles,
-  };
-}
-
-export function runtimeArchitectureCompatibilityError(agent: {
-  runtime: AgentRuntime;
-  architecture?: AgentArchitecture;
-}): string | undefined {
-  return agent.architecture === "v2" && agent.runtime === "grokbot"
-    ? 'architecture: "v2" cannot use runtime: "grokbot": the grokbot runtime executes through the signed-in account\'s hosted /v0/grokbot box, not a deployment-scoped v2 runtime.'
-    : undefined;
-}
-
-function resolveArchitecture(
-  ctx: DiscoveryContext,
-  agentDir: string,
-  architecture: AgentArchitecture | undefined
-): AgentArchitecture | undefined {
-  if (
-    architecture === undefined ||
-    architecture === "v1" ||
-    architecture === "v2"
-  ) {
-    return architecture;
-  }
-  ctx.diagnostics.push({
-    severity: "error",
-    path: displayPath(ctx, join(agentDir, "agent.ts")),
-    message: `architecture must be "v1" or "v2"; got ${JSON.stringify(architecture)}.`,
-  });
-  return undefined;
-}
-
-/** 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);
-}
-
-/**
- * Nested git checkouts inherit ancestor AGENTS.md / .cursor rules and MCP.
- * Point those harnesses at ~/.cache/agent-serve/<dir> unless the agent
- * already set cwd or workspaceDir.
- */
-async function resolveLocalCwd(
-  ctx: DiscoveryContext,
-  authoredCwd: string | undefined,
-  authoredWorkspaceDir: string | undefined
-): Promise<string | undefined> {
-  const cwd = resolveAgentCwd(ctx, authoredCwd);
-  if (cwd !== undefined) {
-    return cwd;
-  }
-  if (resolveAgentCwd(ctx, authoredWorkspaceDir) !== undefined) {
-    return undefined;
-  }
-  if (!(await isNestedInGitRepo(ctx.rootDir))) {
-    return undefined;
-  }
-  return defaultLocalHarnessCwd(basename(ctx.rootDir));
-}
-
-/**
- * Validate the authored `hosting` block against the same grammar the
- * backend enforces on deploy. Violations are warning diagnostics (reported
- * by `agent-sdk validate`), not hard failures: the backend stays
- * authoritative and `agent-sdk deploy` re-checks before any network call.
- */
-function resolveHosting(
-  ctx: DiscoveryContext,
-  agentDir: string,
-  hosting: AgentHostingOptions | undefined
-): AgentHostingOptions | undefined {
-  if (hosting === undefined) {
-    return undefined;
-  }
-  const agentPath = displayPath(ctx, join(agentDir, "agent.ts"));
-  const warn = (message: string): void => {
-    ctx.diagnostics.push({ severity: "warning", path: agentPath, message });
-  };
-
-  const egressDomains = hosting.egressDomains ?? [];
-  for (const domain of egressDomains) {
-    const domainError = validateEgressDomain(domain);
-    if (domainError !== undefined) {
-      warn(`hosting.egressDomains: ${domainError}`);
-    }
-  }
-  if (egressDomains.length > MAX_EGRESS_DOMAINS) {
-    warn(
-      `hosting.egressDomains lists ${egressDomains.length} domains; deploys are capped at ${MAX_EGRESS_DOMAINS}.`
-    );
-  }
-
-  for (const name of hosting.secretNames ?? []) {
-    const nameError = validateSecretName(name);
-    if (nameError !== undefined) {
-      warn(`hosting.secretNames: ${nameError}`);
-    } else if (isReservedSecretName(name)) {
-      warn(
-        `hosting.secretNames: ${JSON.stringify(name)} is platform-managed (CURSOR_* / reserved hosted-storage names); omit it from secretNames.`
-      );
-    }
-  }
-
-  return {
-    ...(hosting.egressDomains === undefined
-      ? {}
-      : { egressDomains: [...hosting.egressDomains] }),
-    ...(hosting.secretNames === undefined
-      ? {}
-      : { secretNames: [...hosting.secretNames] }),
-  };
-}
-
-/**
- * Validate the authored `concurrency` block. Invalid values are **error**
- * diagnostics (serve refuses to start): silently dropping a turn ceiling
- * would fail open to unlimited parallelism, the opposite of what the
- * author asked for.
- */
-function resolveConcurrency(
-  ctx: DiscoveryContext,
-  agentDir: string,
-  concurrency: AgentConcurrencyOptions | undefined
-): AgentConcurrencyOptions | undefined {
-  if (concurrency === undefined || concurrency.maxRunningTurns === undefined) {
-    return undefined;
-  }
-  try {
-    return {
-      maxRunningTurns: normalizePositiveInt(concurrency.maxRunningTurns, {
-        label: "concurrency.maxRunningTurns",
-        max: MAX_RUNNING_TURNS_LIMIT,
-      }),
-    };
-  } catch (error) {
-    ctx.diagnostics.push({
-      severity: "error",
-      path: displayPath(ctx, join(agentDir, "agent.ts")),
-      message: error instanceof Error ? error.message : String(error),
-    });
-    return undefined;
-  }
-}
-
-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[]> {
-  const tools: DiscoveredTool[] = [];
-  for (const { name, path } of await toolModuleEntries(ctx, toolsDir)) {
-    const definition = await importDefault(ctx, path, "tool");
-    if (definition === undefined) {
-      continue;
-    }
-    const tool = compileTool(ctx, path, name, definition as ToolDefinition);
-    if (tool !== undefined) {
-      tools.push(tool);
-    }
-  }
-  return tools;
-}
-
-/** The module files of a `tools/` directory whose filenames are valid tool names. */
-async function toolModuleEntries(
-  ctx: DiscoveryContext,
-  toolsDir: string
-): Promise<Array<{ name: string; path: string }>> {
-  if (!(await isDirectory(toolsDir))) {
-    return [];
-  }
-  const entries: Array<{ name: string; path: string }> = [];
-  for (const entry of await sortedEntries(toolsDir)) {
-    const path = join(toolsDir, entry.name);
-    if (entry.isDirectory()) {
-      ctx.diagnostics.push({
-        severity: "warning",
-        path: displayPath(ctx, path),
-        message: "Nested tool directories are not supported; ignoring.",
-      });
-      continue;
-    }
-    if (!entry.isFile() || !isModuleFile(entry.name)) {
-      continue;
-    }
-    const name = moduleStem(entry.name);
-    if (validateName(ctx, "tool", name, path)) {
-      entries.push({ name, path });
-    }
-  }
-  return entries;
-}
-
-/**
- * Validate one tool definition against the tool contract and convert its
- * schemas. Diagnostics point at `entryPath` (the authored file, or the
- * extension mount that contributed the tool).
- */
-function compileTool(
-  ctx: DiscoveryContext,
-  entryPath: string,
-  name: string,
-  tool: ToolDefinition
-): DiscoveredTool | undefined {
-  if (isBlank(tool.description)) {
-    ctx.diagnostics.push({
-      severity: "error",
-      path: displayPath(ctx, entryPath),
-      message: "Tools require a non-empty description.",
-    });
-    return undefined;
-  }
-  const execution = tool.execution === "agent" ? "agent" : "server";
-  const needsApprovalConfigured =
-    tool.needsApproval === true || typeof tool.needsApproval === "function";
-  const effect = declaredEffect(tool);
-  if (execution === "agent") {
-    if (isBlank(tool.script)) {
-      ctx.diagnostics.push({
-        severity: "error",
-        path: displayPath(ctx, entryPath),
-        message:
-          'Tools with execution: "agent" require a non-empty `script` (shell body; JSON on stdin, result on stdout).',
-      });
-      return undefined;
-    }
-    if (typeof tool.execute === "function") {
-      ctx.diagnostics.push({
-        severity: "warning",
-        path: displayPath(ctx, entryPath),
-        message:
-          '`execute` is ignored when execution is "agent"; the Cursor agent runs `script` instead.',
-      });
-    }
-    if (needsApprovalConfigured) {
-      ctx.diagnostics.push({
-        severity: "error",
-        path: displayPath(ctx, entryPath),
-        message:
-          '`needsApproval` is only supported for execution: "server" tools (in-process).',
-      });
-      return undefined;
-    }
-  } else if (typeof tool.execute !== "function") {
-    ctx.diagnostics.push({
-      severity: "error",
-      path: displayPath(ctx, entryPath),
-      message:
-        'Tools require an execute(input, ctx) function (or set execution: "agent" with a script).',
-    });
-    return undefined;
-  }
-  let inputSchema: DiscoveredTool["inputSchema"];
-  try {
-    inputSchema = toolInputJsonSchema(tool.inputSchema);
-  } catch (error) {
-    ctx.diagnostics.push({
-      severity: "error",
-      path: displayPath(ctx, entryPath),
-      message: `Failed to convert inputSchema to JSON Schema: ${errorMessage(error)}`,
-    });
-    return undefined;
-  }
-  let outputSchema: DiscoveredTool["outputSchema"];
-  try {
-    outputSchema = toolOutputJsonSchema(tool.outputSchema);
-  } catch (error) {
-    ctx.diagnostics.push({
-      severity: "error",
-      path: displayPath(ctx, entryPath),
-      message: `Failed to convert outputSchema to JSON Schema: ${errorMessage(error)}`,
-    });
-    return undefined;
-  }
-  return {
-    name,
-    description: tool.description,
-    inputSchema,
-    outputSchema,
-    execution,
-    needsApproval: needsApprovalConfigured,
-    effect,
-    script: execution === "agent" ? tool.script : undefined,
-    definition: tool,
-  };
-}
-
-/**
- * Static view of a tool's `effect` for the manifest: the literal when it is
- * one, `"dynamic"` for a per-call predicate, `undefined` when undeclared. A
- * malformed value is left undeclared rather than guessed — undeclared is the
- * safe state (a dry run stubs it), where a guess could be the unsafe one.
- */
-function declaredEffect(
-  tool: ToolDefinition
-): ToolEffect | "dynamic" | undefined {
-  if (typeof tool.effect === "function") {
-    return "dynamic";
-  }
-  return tool.effect === "read" || tool.effect === "write"
-    ? tool.effect
-    : undefined;
-}
-
-// ============================================================================
-// 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 (!validateName(ctx, "skill", 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 (!validateName(ctx, "skill", name, entryPath)) {
-        continue;
-      }
-      const definition = await importDefault(ctx, entryPath, "skill");
-      if (definition === undefined) {
-        continue;
-      }
-      skills.push(compileSkill(name, definition as SkillDefinition));
-    }
-  }
-  return skills;
-}
-
-/** A skill whose body and sibling files are in memory (`defineSkill`, extensions). */
-function compileSkill(name: string, skill: SkillConfig): DiscoveredSkill {
-  const files: Record<string, SkillFileSource> = {};
-  for (const [rel, contents] of Object.entries(skill.files ?? {})) {
-    files[rel] = { contents };
-  }
-  return {
-    name,
-    description:
-      skill.description ??
-      deriveSkillDescription(skill.markdown) ??
-      SKILL_DESCRIPTION_FALLBACK(name),
-    markdown: skill.markdown.trim(),
-    files,
-  };
-}
-
-// ============================================================================
-// Extensions (agent/extensions/<ns>.ts | agent/extensions/<ns>/extension.ts)
-// ============================================================================
-
-/**
- * Mount every extension under `agent/extensions/` and append its tools and
- * skills to the authored lists as `<ns>__<name>`, stamped with `extension`.
- * The namespace is the mount's filename stem or directory name.
- */
-async function appendExtensions(
-  ctx: DiscoveryContext,
-  extensionsDir: string,
-  tools: DiscoveredTool[],
-  skills: DiscoveredSkill[]
-): Promise<DiscoveredExtension[]> {
-  if (!(await isDirectory(extensionsDir))) {
-    return [];
-  }
-  const extensions: DiscoveredExtension[] = [];
-  for (const entry of await sortedEntries(extensionsDir)) {
-    const path = join(extensionsDir, entry.name);
-    const site = await resolveMountSite(ctx, path, entry);
-    if (site === undefined) {
-      continue;
-    }
-    if (extensions.some((extension) => extension.name === site.ns)) {
-      ctx.diagnostics.push({
-        severity: "error",
-        path: displayPath(ctx, path),
-        message: `Extension "${site.ns}" is mounted twice (as a file and as a directory).`,
-      });
-      continue;
-    }
-    const mount = await importDefault(ctx, site.mountPath, "extension");
-    if (mount === undefined) {
-      continue;
-    }
-    extensions.push(
-      await mountExtension(ctx, site, mount as ExtensionMount, tools, skills)
-    );
-  }
-  return extensions;
-}
-
-interface MountSite {
-  ns: string;
-  /** The module default-exporting the {@link ExtensionMount}. */
-  mountPath: string;
-  /** A directory mount; its `tools/` and `skills/` overlay the extension's. */
-  overlayDir?: string;
-}
-
-async function resolveMountSite(
-  ctx: DiscoveryContext,
-  path: string,
-  entry: Dirent
-): Promise<MountSite | undefined> {
-  if (entry.isDirectory()) {
-    if (!validateName(ctx, "extension", entry.name, path)) {
-      return undefined;
-    }
-    const mountPath = await findModuleFile(path, "extension");
-    if (mountPath === undefined) {
-      ctx.diagnostics.push({
-        severity: "error",
-        path: displayPath(ctx, path),
-        message:
-          "A directory mount needs an extension.ts default-exporting the mount (`export default crm({ ... })`).",
-      });
-      return undefined;
-    }
-    return { ns: entry.name, mountPath, overlayDir: path };
-  }
-  if (!entry.isFile() || !isModuleFile(entry.name)) {
-    return undefined;
-  }
-  const ns = moduleStem(entry.name);
-  return validateName(ctx, "extension", ns, path)
-    ? { ns, mountPath: path }
-    : undefined;
-}
-
-/**
- * Read the extension's tree with the agent loaders, lay the mount's overlay
- * on top (a same-named file replaces, `disableTool()` removes), then
- * namespace what is left.
- */
-async function mountExtension(
-  ctx: DiscoveryContext,
-  site: MountSite,
-  mount: ExtensionMount,
-  tools: DiscoveredTool[],
-  skills: DiscoveredSkill[]
-): Promise<DiscoveredExtension> {
-  const mounted: DiscoveredExtension = {
-    name: site.ns,
-    description: mount.extension.description,
-    tools: [],
-    skills: [],
-  };
-  const root = mount.extension.root;
-  if (!(await isDirectory(root))) {
-    ctx.diagnostics.push({
-      severity: "error",
-      path: displayPath(ctx, site.mountPath),
-      message: `Extension "${site.ns}" declares root ${root}, which is not a directory. Pass \`import.meta.dirname\` from extension.ts.`,
-    });
-    return mounted;
-  }
-  await warnUnsupportedExtensionSlots(ctx, root);
-  const contributedTools = new Map(
-    (await loadTools(ctx, join(root, "tools"))).map((tool) => [tool.name, tool])
-  );
-  const contributedSkills = new Map(
-    (await loadSkills(ctx, join(root, "skills"))).map((skill) => [
-      skill.name,
-      skill,
-    ])
-  );
-  if (site.overlayDir !== undefined) {
-    const overlay = await loadOverlayTools(ctx, join(site.overlayDir, "tools"));
-    for (const tool of overlay.tools) {
-      contributedTools.set(tool.name, tool);
-    }
-    for (const disabled of overlay.disabled) {
-      if (!contributedTools.delete(disabled.name)) {
-        ctx.diagnostics.push({
-          severity: "error",
-          path: displayPath(ctx, disabled.path),
-          message: `disableTool() targets "${disabled.name}", which extension "${site.ns}" does not contribute.`,
-        });
-      }
-    }
-    for (const skill of await loadSkills(
-      ctx,
-      join(site.overlayDir, "skills")
-    )) {
-      contributedSkills.set(skill.name, skill);
-    }
-  }
-  for (const [name, tool] of contributedTools) {
-    const composed = `${site.ns}__${name}`;
-    tools.push({ ...tool, name: composed, extension: site.ns });
-    mounted.tools.push(composed);
-  }
-  for (const [name, skill] of contributedSkills) {
-    const composed = `${site.ns}__${name}`;
-    skills.push({ ...skill, name: composed, extension: site.ns });
-    mounted.skills.push(composed);
-  }
-  return mounted;
-}
-
-/** A directory mount's `tools/`: replacements plus `disableTool()` markers. */
-async function loadOverlayTools(
-  ctx: DiscoveryContext,
-  toolsDir: string
-): Promise<{
-  tools: DiscoveredTool[];
-  disabled: Array<{ name: string; path: string }>;
-}> {
-  const tools: DiscoveredTool[] = [];
-  const disabled: Array<{ name: string; path: string }> = [];
-  for (const { name, path } of await toolModuleEntries(ctx, toolsDir)) {
-    let mod: Record<string, unknown>;
-    try {
-      mod = await ctx.importModule(path);
-    } catch (error) {
-      ctx.diagnostics.push({
-        severity: "error",
-        path: displayPath(ctx, path),
-        message: `Failed to load module: ${errorMessage(error)}`,
-      });
-      continue;
-    }
-    const kind = getDefinitionKind(mod.default);
-    if (kind === "disabled-tool") {
-      disabled.push({ name, path });
-      continue;
-    }
-    if (kind !== "tool") {
-      ctx.diagnostics.push({
-        severity: "error",
-        path: displayPath(ctx, path),
-        message:
-          "An override must default-export defineTool({ ... }) or disableTool().",
-      });
-      continue;
-    }
-    const tool = compileTool(ctx, path, name, mod.default as ToolDefinition);
-    if (tool !== undefined) {
-      tools.push(tool);
-    }
-  }
-  return { tools, disabled };
-}
-
-/** Slots an agent has that an extension tree may not contribute (yet). */
-async function warnUnsupportedExtensionSlots(
-  ctx: DiscoveryContext,
-  root: string
-): Promise<void> {
-  const unsupported = [
-    ["instructions.md", "instructions"],
-    ["connections", "connections"],
-    ["mcp-connections", "MCP connections"],
-    ["hooks", "hooks"],
-    ["subagents", "subagents"],
-    ["channels", "channels"],
-    ["schedules", "schedules"],
-    ["extensions", "nested extensions"],
-  ] as const;
-  for (const [slot, label] of unsupported) {
-    const path = join(root, slot);
-    if ((await isDirectory(path)) || (await isFile(path))) {
-      ctx.diagnostics.push({
-        severity: "warning",
-        path: displayPath(ctx, path),
-        message: `Extension ${label} are not supported yet; only tools/ and skills/ are mounted. Ignoring.`,
-      });
-    }
-  }
-}
-
-async function loadPackagedSkill(
-  ctx: DiscoveryContext,
-  skillDir: string,
-  name: string
-): Promise<DiscoveredSkill | undefined> {
-  const skillMdPath = join(skillDir, "SKILL.md");
-  if (!(await isFile(skillMdPath))) {
-    ctx.diagnostics.push({
-      severity: "warning",
-      path: displayPath(ctx, skillDir),
-      message: "Skill directories must contain a SKILL.md; ignoring.",
-    });
-    return undefined;
-  }
-  if (!validateName(ctx, "skill", name, skillDir)) {
-    return undefined;
-  }
-  const { data, body } = parseFrontmatter(await readFile(skillMdPath, "utf8"));
-  if (data.description === undefined || isBlank(data.description)) {
-    ctx.diagnostics.push({
-      severity: "error",
-      path: displayPath(ctx, skillMdPath),
-      message:
-        "Packaged skills require `description` frontmatter in SKILL.md (there is no filename slug to fall back on).",
-    });
-    return undefined;
-  }
-
-  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.oauth === true
-      ? `${transport.url} (oauth)`
-      : transport.url;
-  }
-  return transport.command;
-}
-
-function hasAuthorizationHeader(
-  headers: Record<string, string> | undefined
-): boolean {
-  if (headers === undefined) {
-    return false;
-  }
-  return Object.keys(headers).some(
-    (key) => key.toLowerCase() === "authorization"
-  );
-}
-
-function parseConnectionEffects(
-  effects: unknown
-): { ok: true; value: ToolEffect[] | undefined } | { ok: false } {
-  if (effects === undefined) {
-    return { ok: true, value: undefined };
-  }
-  const raw = typeof effects === "string" ? [effects] : effects;
-  if (!Array.isArray(raw) || raw.length === 0) {
-    return { ok: false };
-  }
-  const parsed: ToolEffect[] = [];
-  for (const value of raw) {
-    if (!isToolEffect(value)) {
-      return { ok: false };
-    }
-    parsed.push(value);
-  }
-  return { ok: true, value: normalizeConnectionEffects(parsed) };
-}
-
-function parseConnectionTools(
-  tools: unknown
-): { ok: true; value: string[] | undefined } | { ok: false } {
-  if (tools === undefined) {
-    return { ok: true, value: undefined };
-  }
-  if (!Array.isArray(tools) || tools.length === 0) {
-    return { ok: false };
-  }
-  if (tools.some((name) => typeof name !== "string")) {
-    return { ok: false };
-  }
-  const normalized = normalizeConnectionTools(tools);
-  if (normalized.length === 0) {
-    return { ok: false };
-  }
-  return { ok: true, value: normalized };
-}
-
-function connectionHasSpawnOrRemote(connection: ConnectionDefinition): boolean {
-  if ("cursorAccount" in connection && connection.cursorAccount === true) {
-    return true;
-  }
-  if ("agent" in connection && !isBlank(connection.agent)) {
-    return true;
-  }
-  if ("url" in connection && !isBlank(connection.url)) {
-    return true;
-  }
-  return "command" in connection && !isBlank(connection.command);
-}
-
-function connectionTransport(
-  connection: ConnectionDefinition
-): ConnectionTransport | undefined {
-  if ("cursorAccount" in connection && connection.cursorAccount === true) {
-    const servers = normalizeCursorAccountServers(connection.servers);
-    return {
-      cursorAccount: true,
-      ...(servers === undefined ? {} : { servers }),
-    };
-  }
-  if ("agent" in connection && !isBlank(connection.agent)) {
-    return { agent: connection.agent };
-  }
-  if ("url" in connection && !isBlank(connection.url)) {
-    return {
-      type: connection.type,
-      url: connection.url,
-      headers: connection.headers,
-      oauth: connection.oauth === true ? true : undefined,
-    };
-  }
-  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;
-}
-
-/**
- * Filenames become the names the model sees. `__` is reserved: it joins an
- * extension's namespace to its contribution (`crm__search`).
- */
-function validateName(
-  ctx: DiscoveryContext,
-  kind: "skill" | "tool" | "extension",
-  name: string,
-  entryPath: string
-): boolean {
-  const label = { skill: "Skill", tool: "Tool", extension: "Extension" }[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;
-}
-
-/**
- * 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 loadHostConnections(
-  ctx: DiscoveryContext,
-  agentDir: string,
-  modelConnections: readonly DiscoveredConnection[]
-): Promise<DiscoveredConnection[]> {
-  const hostDir = join(agentDir, "host-connections");
-  const loaded = await loadConnections(ctx, hostDir, "host");
-  const modelNames = new Set(
-    modelConnections.map((connection) => connection.name)
-  );
-  const hostConnections: DiscoveredConnection[] = [];
-  for (const connection of loaded) {
-    if (modelNames.has(connection.name)) {
-      ctx.diagnostics.push({
-        severity: "error",
-        path: displayPath(ctx, join(hostDir, `${connection.name}.ts`)),
-        message: `Host connection "${connection.name}" collides with agent/mcp-connections/${connection.name}. Rename one of them.`,
-      });
-      continue;
-    }
-    if (connection.advertiseTools === true) {
-      ctx.diagnostics.push({
-        severity: "error",
-        path: displayPath(ctx, join(hostDir, `${connection.name}.ts`)),
-        message:
-          "Host connections are off the model. `advertiseTools` cannot apply. Drop it.",
-      });
-      continue;
-    }
-    if (connection.auth !== undefined) {
-      ctx.diagnostics.push({
-        severity: "error",
-        path: displayPath(ctx, join(hostDir, `${connection.name}.ts`)),
-        message:
-          "Host connections are off the model. `auth` cannot apply. Use static headers or `oauth: true`.",
-      });
-      continue;
-    }
-    hostConnections.push(connection);
-  }
-  return hostConnections;
-}
-
-async function loadConnections(
-  ctx: DiscoveryContext,
-  connectionsDir: string,
-  role: "model" | "host" = "model"
-): 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;
-    if (Object.hasOwn(connection, "hostOnly")) {
-      ctx.diagnostics.push({
-        severity: "error",
-        path: displayPath(ctx, entryPath),
-        message:
-          "MCP connection `hostOnly` was removed. Files under `agent/mcp-connections/` are always visible to the model. Put privileged servers in `agent/host-connections/` so only host tools can call them.",
-      });
-      continue;
-    }
-    if (
-      isInlineStdioConnection(connection) &&
-      connectionHasSpawnOrRemote(connection)
-    ) {
-      ctx.diagnostics.push({
-        severity: "error",
-        path: displayPath(ctx, entryPath),
-        message:
-          "MCP connection `tools` cannot be combined with `command`, `url`, `agent`, or `cursorAccount`. Author TypeScript tools, or point at an existing server, not both.",
-      });
-      continue;
-    }
-    if (
-      connection.auth !== undefined &&
-      typeof connection.auth !== "function"
-    ) {
-      ctx.diagnostics.push({
-        severity: "error",
-        path: displayPath(ctx, entryPath),
-        message:
-          "MCP connection `auth` must be a function: (session) => { headers }.",
-      });
-      continue;
-    }
-    if (connection.auth !== undefined && !("url" in connection)) {
-      ctx.diagnostics.push({
-        severity: "error",
-        path: displayPath(ctx, entryPath),
-        message:
-          "MCP connection `auth` (per-session headers) is only supported on http/sse connections (`url`).",
-      });
-      continue;
-    }
-    if (
-      connection.advertiseTools !== undefined &&
-      typeof connection.advertiseTools !== "boolean"
-    ) {
-      ctx.diagnostics.push({
-        severity: "error",
-        path: displayPath(ctx, entryPath),
-        message: "MCP connection `advertiseTools` must be a boolean.",
-      });
-      continue;
-    }
-    const parsedEffects = parseConnectionEffects(connection.effects);
-    if (!parsedEffects.ok) {
-      ctx.diagnostics.push({
-        severity: "error",
-        path: displayPath(ctx, entryPath),
-        message:
-          'MCP connection `effects` must be "read", "write", or a non-empty array of those.',
-      });
-      continue;
-    }
-    if (
-      parsedEffects.value !== undefined &&
-      connection.advertiseTools !== true
-    ) {
-      ctx.diagnostics.push({
-        severity: "error",
-        path: displayPath(ctx, entryPath),
-        message:
-          "MCP connection `effects` filters advertised tools; set `advertiseTools: true` or drop `effects`.",
-      });
-      continue;
-    }
-    const parsedTools = isInlineStdioConnection(connection)
-      ? { ok: true as const, value: undefined }
-      : parseConnectionTools(connection.tools);
-    if (!parsedTools.ok) {
-      ctx.diagnostics.push({
-        severity: "error",
-        path: displayPath(ctx, entryPath),
-        message:
-          "MCP connection `tools` allowlist must be a non-empty array of tool names.",
-      });
-      continue;
-    }
-    if (
-      isInlineStdioConnection(connection) &&
-      connection.disallowedTools !== undefined
-    ) {
-      ctx.diagnostics.push({
-        severity: "error",
-        path: displayPath(ctx, entryPath),
-        message:
-          "MCP connection `disallowedTools` is not supported on inline `tools` connections — author only the tools you want.",
-      });
-      continue;
-    }
-    const parsedDisallowed = isInlineStdioConnection(connection)
-      ? { ok: true as const, value: undefined }
-      : parseConnectionTools(connection.disallowedTools);
-    if (!parsedDisallowed.ok) {
-      ctx.diagnostics.push({
-        severity: "error",
-        path: displayPath(ctx, entryPath),
-        message:
-          "MCP connection `disallowedTools` must be a non-empty array of tool names.",
-      });
-      continue;
-    }
-    if (
-      (parsedTools.value !== undefined ||
-        parsedDisallowed.value !== undefined) &&
-      role === "model" &&
-      connection.advertiseTools !== true
-    ) {
-      ctx.diagnostics.push({
-        severity: "error",
-        path: displayPath(ctx, entryPath),
-        message:
-          "MCP connection `tools` / `disallowedTools` filter advertised tools; set `advertiseTools: true` or drop the name list. Put the connection in `agent/host-connections/` to restrict `host.mcp` only.",
-      });
-      continue;
-    }
-    if (
-      connection.advertiseTools === true &&
-      isInlineStdioConnection(connection)
-    ) {
-      ctx.diagnostics.push({
-        severity: "error",
-        path: displayPath(ctx, entryPath),
-        message:
-          "MCP connection `advertiseTools` is not supported on inline `tools` connections — author those as agent/tools/ server tools instead.",
-      });
-      continue;
-    }
-    if (
-      connection.auth !== undefined &&
-      "url" in connection &&
-      connection.oauth === true
-    ) {
-      ctx.diagnostics.push({
-        severity: "error",
-        path: displayPath(ctx, entryPath),
-        message:
-          "MCP connection `oauth: true` cannot be combined with `auth` (per-session headers): the host OAuth provider owns the Authorization header. Drop one of them.",
-      });
-      continue;
-    }
-    if (isInlineStdioConnection(connection)) {
-      const packed = await loadInlineStdioConnection(
-        ctx,
-        name,
-        entryPath,
-        connection
-      );
-      if (packed === undefined) {
-        continue;
-      }
-      connections.push(packed);
-      continue;
-    }
-    if (
-      "url" in connection &&
-      connection.oauth === true &&
-      hasAuthorizationHeader(connection.headers)
-    ) {
-      ctx.diagnostics.push({
-        severity: "error",
-        path: displayPath(ctx, entryPath),
-        message:
-          "MCP connection `oauth: true` cannot set an Authorization header. Drop the header or remove `oauth`.",
-      });
-      continue;
-    }
-    if (
-      "cursorAccount" in connection &&
-      connection.cursorAccount === true &&
-      cursorAccountServersHasMixedWildcard(connection.servers)
-    ) {
-      ctx.diagnostics.push({
-        severity: "error",
-        path: displayPath(ctx, entryPath),
-        message:
-          'Cursor account MCP connection `servers` cannot mix `"*"` with connector names. Use `"*"` / `["*"]` (or omit `servers`) for every connected server, or list only concrete connector names.',
-      });
-      continue;
-    }
-    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), `tools` (TypeScript packaged as 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, `"*"` / `["*"]` for every connected server, or omitted for the same all-connectors behavior.',
-      });
-      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,
-      description: connection.description,
-      auth: connection.auth,
-      advertiseTools: connection.advertiseTools,
-      effects: parsedEffects.value,
-      tools: parsedTools.value,
-      disallowedTools: parsedDisallowed.value,
-    });
-  }
-  return connections;
-}
-
-async function loadInlineStdioConnection(
-  ctx: DiscoveryContext,
-  name: string,
-  entryPath: string,
-  connection: InlineStdioConnectionConfig & {
-    description?: string;
-  }
-): Promise<DiscoveredConnection | undefined> {
-  const tools = connection.tools;
-  const names = Object.keys(tools);
-  if (names.length === 0) {
-    ctx.diagnostics.push({
-      severity: "error",
-      path: displayPath(ctx, entryPath),
-      message: "MCP connection `tools` must declare at least one tool.",
-    });
-    return undefined;
-  }
-  for (const toolName of names) {
-    if (!NAME_PATTERN.test(toolName)) {
-      ctx.diagnostics.push({
-        severity: "error",
-        path: displayPath(ctx, entryPath),
-        message: `MCP tool name "${toolName}" must match ${NAME_PATTERN}.`,
-      });
-      return undefined;
-    }
-    const tool = tools[toolName];
-    if (tool === undefined || isBlank(tool.description)) {
-      ctx.diagnostics.push({
-        severity: "error",
-        path: displayPath(ctx, entryPath),
-        message: `MCP tool "${toolName}" requires a non-empty description.`,
-      });
-      return undefined;
-    }
-    if (typeof tool.execute !== "function") {
-      ctx.diagnostics.push({
-        severity: "error",
-        path: displayPath(ctx, entryPath),
-        message: `MCP tool "${toolName}" requires an execute(input) function.`,
-      });
-      return undefined;
-    }
-  }
-  try {
-    const transport = await packageInlineStdioConnection({
-      name,
-      entryPath,
-      tools,
-      absWorkingDir: ctx.rootDir,
-    });
-    return {
-      name,
-      transport,
-      description: connection.description,
-    };
-  } catch (error) {
-    ctx.diagnostics.push({
-      severity: "error",
-      path: displayPath(ctx, entryPath),
-      message: `Failed to package inline stdio MCP connection: ${errorMessage(error)}`,
-    });
-    return undefined;
-  }
-}
-
-// ============================================================================
-// 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"],
-    ["extensions", "extensions"],
-    ["mcp-connections", "MCP connections"],
-    ["host-connections", "host 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.`,
-      });
-    }
-  }
-}
-
-/**
- * Append enabled built-in tools after authored tools. Authored tools with
- * the same name win.
- */
-function appendBuiltinTools(
-  ctx: DiscoveryContext,
-  agentDir: string,
-  tools: DiscoveredTool[],
-  config: BuiltinToolsConfig | undefined
-): void {
-  const builtin = builtinTools(config);
-  if (builtin.length === 0) {
-    return;
-  }
-  const agentPath = displayPath(ctx, join(agentDir, "agent.ts"));
-  for (const tool of builtin) {
-    const existing = tools.find((t) => t.name === tool.name);
-    if (existing !== undefined) {
-      const owner =
-        existing.extension === undefined
-          ? "Authored"
-          : `Extension "${existing.extension}"`;
-      ctx.diagnostics.push({
-        severity: "warning",
-        path: agentPath,
-        message: `${owner} tool "${tool.name}" shadows the built-in tool of the same name; the built-in is skipped.`,
-      });
-      continue;
-    }
-    tools.push(tool);
-  }
-}
-
-/**
- * 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.
- */
-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.
- */
-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.'
-    );
-  }
-}
-
-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.",
-    });
-  }
-}
-
-// ============================================================================
-// 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;
-    }
-    const definition = mod.default as ChannelDefinition;
-    for (const notice of definition.meta?.deprecations ?? []) {
-      ctx.diagnostics.push({
-        severity: "warning",
-        path: displayPath(ctx, entryPath),
-        message: notice,
-      });
-    }
-    channels.push({ id, definition });
-  }
-  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 @cursor/july/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;
-  }
-}
-
-// ============================================================================
-// Storage (agent/storage.ts)
-// ============================================================================
-
-async function loadStorage(
-  ctx: DiscoveryContext,
-  agentDir: string,
-  architecture: AgentArchitecture | undefined
-): Promise<StorageDefinition | undefined> {
-  const path = await findModuleFile(agentDir, "storage");
-  if (path === undefined) {
-    return undefined;
-  }
-  if (architecture === "v2") {
-    // Storage is a hosting-mode decision on v2, made by
-    // framework-storage-selection.ts: the state root when self-hosted,
-    // Cursor-managed storage on Cursor hosting. Fail early (error
-    // diagnostics refuse serve and deploy) rather than silently running
-    // with storage the author believes they configured. Not imported.
-    ctx.diagnostics.push({
-      severity: "error",
-      path: displayPath(ctx, path),
-      message:
-        'agent/storage.ts is not supported on architecture "v2": the platform selects storage (the local state root when self-hosted; Cursor-managed storage on Cursor hosting). Delete the file.',
-    });
-    return undefined;
-  }
-  // v1 keeps loading the authored sink, with notice: defineStorage is going
-  // away with the v1 control plane.
-  ctx.diagnostics.push({
-    severity: "warning",
-    path: displayPath(ctx, path),
-    message:
-      'agent/storage.ts (defineStorage) is deprecated and going away: architecture "v2" selects storage automatically (the local state root when self-hosted; Cursor-managed storage on Cursor hosting). Still honored on v1.',
-  });
-  const definition = await importDefault(ctx, path, "storage");
-  return definition as StorageDefinition | undefined;
-}
-
-// ============================================================================
-// OpenTelemetry (agent/otel.ts)
-// ============================================================================
-
-async function loadOtel(
-  ctx: DiscoveryContext,
-  agentDir: string
-): Promise<OtelDefinition | undefined> {
-  const path = await findModuleFile(agentDir, "otel");
-  if (path === undefined) {
-    return undefined;
-  }
-  const definition = await importDefault(ctx, path, "otel");
-  return definition as OtelDefinition | undefined;
-}
-
-// ============================================================================
-// Artifacts (agent/artifacts.ts)
-// ============================================================================
-
-async function loadArtifacts(
-  ctx: DiscoveryContext,
-  agentDir: string
-): Promise<ArtifactsDefinition | undefined> {
-  const path = await findModuleFile(agentDir, "artifacts");
-  if (path === undefined) {
-    return undefined;
-  }
-  const imported = await importDefault(ctx, path, "artifacts");
-  if (imported === undefined) {
-    return undefined;
-  }
-  const definition = imported as ArtifactsDefinition;
-  if (
-    definition.agentTool === true &&
-    Object.keys(definition.kinds ?? {}).length === 0
-  ) {
-    ctx.diagnostics.push({
-      severity: "error",
-      path: displayPath(ctx, path),
-      message:
-        "artifacts.agentTool requires kinds: the tag_artifact tool needs at least one declared kind; its descriptions are the tool prompt.",
-    });
-  }
-  return definition;
-}
-
-/**
- * Materialize the `tag_artifact` built-in when `defineArtifacts` set
- * `agentTool: true`. Appended after `loadAgent` because the tool is
- * generated from the artifacts kinds registry, not `AgentConfig.builtinTools`.
- */
-async function appendArtifactTool(
-  ctx: DiscoveryContext,
-  agentDir: string,
-  agent: ResolvedAgent,
-  artifacts: ArtifactsDefinition | undefined
-): Promise<void> {
-  const tool = artifactBuiltinTool(artifacts);
-  if (tool === undefined) {
-    return;
-  }
-  const artifactsPath = displayPath(
-    ctx,
-    (await findModuleFile(agentDir, "artifacts")) ??
-      join(agentDir, "artifacts.ts")
-  );
-  if (agent.tools.some((t) => t.name === TAG_ARTIFACT_TOOL_NAME)) {
-    ctx.diagnostics.push({
-      severity: "warning",
-      path: artifactsPath,
-      message: `Authored tool "${TAG_ARTIFACT_TOOL_NAME}" shadows the built-in tool of the same name; the authored tool wins.`,
-    });
-    return;
-  }
-  agent.tools.push(tool);
-}
-
-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,
-    description: agent.description,
-    model: agent.model,
-    runtime: agent.runtime,
-    cloud:
-      agent.cloud === undefined ? undefined : toPublicCloudInfo(agent.cloud),
-    local: agent.local,
-    hosting: agent.hosting,
-    concurrency: agent.concurrency,
-    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,
-      effect: tool.effect,
-      inputSchema: tool.inputSchema,
-    })),
-    skills: agent.skills.map((skill) => ({
-      name: skill.name,
-      description: skill.description,
-    })),
-    extensions: agent.extensions ?? [],
-    connections: agent.connections.map((connection) => ({
-      name: connection.name,
-      transport: connectionTransportLabel(connection.transport),
-      advertiseTools: connection.advertiseTools,
-      effects: connection.effects,
-      tools: connection.tools,
-      disallowedTools: connection.disallowedTools,
-      cursorAccountServers:
-        "cursorAccount" in connection.transport
-          ? (connection.transport.servers ?? "*")
-          : undefined,
-    })),
-    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?.originWebhookEvents !== undefined) {
-          info.originWebhookEvents = meta.originWebhookEvents;
-        }
-        if (meta?.deploymentEventTypes !== undefined) {
-          info.deploymentEventTypes = meta.deploymentEventTypes;
-        }
-        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.storage?.abs !== undefined,
-            durableSnapshots: project.storage?.abs?.putSnapshot !== undefined,
-          },
-        }),
-    storage:
-      project.storage === undefined
-        ? undefined
-        : { name: project.storage.name },
-    artifacts:
-      project.artifacts === undefined
-        ? undefined
-        : {
-            kinds: Object.keys(project.artifacts.kinds ?? {}),
-            agentTool: project.artifacts.agentTool === true,
-            max: resolveArtifactsMax(project.artifacts),
-          },
-    otel:
-      project.otel === undefined
-        ? undefined
-        : {
-            enabled: true as const,
-            serviceName: project.otel.serviceName,
-          },
-    diagnostics: project.diagnostics,
-  };
-}
-
-// ============================================================================
-// Shared helpers
-// ============================================================================
-
-async function importDefault(
-  ctx: DiscoveryContext,
-  modulePath: string,
-  expectedKind:
-    | "agent"
-    | "tool"
-    | "skill"
-    | "extension"
-    | "connection"
-    | "schedule"
-    | "hook"
-    | "ab"
-    | "storage"
-    | "artifacts"
-    | "otel"
-): 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 = DEFINE_HELPER_NAME[expectedKind];
-    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;
-}
-
-const DEFINE_HELPER_NAME: Record<
-  | "agent"
-  | "instructions"
-  | "tool"
-  | "skill"
-  | "extension"
-  | "connection"
-  | "channel"
-  | "http-channel"
-  | "schedule"
-  | "hook"
-  | "ab"
-  | "storage"
-  | "artifacts"
-  | "otel",
-  string
-> = {
-  agent: "defineAgent",
-  instructions: "defineInstructions",
-  tool: "defineTool",
-  skill: "defineSkill",
-  extension: "defineExtension",
-  connection: "defineConnection",
-  channel: "defineChannel",
-  "http-channel": "httpChannel",
-  schedule: "defineSchedule",
-  hook: "defineHook",
-  ab: "defineAB",
-  storage: "defineStorage",
-  artifacts: "defineArtifacts",
-  otel: "defineOtel",
-};
-
-async function warnUnknownSlots(
-  ctx: DiscoveryContext,
-  agentDir: string
-): Promise<void> {
-  const known = new Set([
-    "agent",
-    "instructions",
-    "tools",
-    "skills",
-    "extensions",
-    "mcp-connections",
-    "host-connections",
-    // Legacy slot name; resolveMcpConnectionsDir warns and still loads it.
-    "connections",
-    "subagents",
-    "channels",
-    "schedules",
-    "hooks",
-    "ab",
-    "sandbox",
-    "lib",
-    // Vite playground custom tool chips (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;
-  }
-  if (!MODULE_EXTENSIONS.has(extname(fileName))) {
-    return false;
-  }
-  // Colocated unit tests (Vitest/Jest convention) are not definitions.
-  // Without this, `channels/slack.test.ts` is scanned as a channel named
-  // "slack.test", fails NAME_PATTERN, and the whole agent refuses to serve.
-  const stem = moduleStem(fileName);
-  return !stem.endsWith(".test") && !stem.endsWith(".spec");
-}
-
-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);
-}
+ *
+ * The loaders live under `./discovery/`, one module per authored slot;
+ * this module is the public surface the CLI, server, and tests import.
+ */
+
+export { runtimeArchitectureCompatibilityError } from "./discovery/agent-config.js";
+export type { LoadAgentProjectOptions } from "./discovery/context.js";
+export { projectInfo } from "./discovery/info.js";
+export {
+  type ChildAgentDir,
+  formatDiagnostics,
+  hasErrorDiagnostics,
+  isAgentProjectDir,
+  listChildAgentDirs,
+  loadAgentProject,
+  loadAgentProjects,
+  RESERVED_SLUGS,
+  resolveAgentMounts,
+} from "./discovery/project.js";
+export { deriveSkillDescription } from "./discovery/skills.js";