@cursor/july 0.1.101 → 0.1.103

package/src/internal/deploy-manifest.ts

@@ -31,7 +31,6 @@
 
 import { z } from "zod";
 import { isPublicEndpointPolicy } from "../channels.js";
-import type { ContinuationIdentity } from "../continuation.js";
 import { isCursorHostedStorage } from "../storage-backends/cursor-hosted.js";
 import type { AgentProject, AgentProjectInfo } from "../types.js";
 import {
@@ -40,7 +39,10 @@ import {
   channelDeclaredEventTypes,
   handshakeChannelContinuation,
 } from "./continuation-channel.js";
-import { CONTINUATION_SELECTORS } from "./continuation-identity.js";
+import {
+  CONTINUATION_SELECTORS,
+  type ContinuationIdentity,
+} from "./continuation-identity.js";
 import {
   projectInfo,
   runtimeArchitectureCompatibilityError,

package/src/internal/discovery/ab.ts

@@ -0,0 +1,131 @@
+/**
+ * `agent/ab.ts` or `agent/ab/*.ts` plus `agent/ab.config.ts`: live A/B experiments.
+ */
+
+import { basename, extname, join, relative } from "node:path";
+import type { ABConfigFile } from "../../ab.js";
+import type { DiscoveredAB } from "../../types.js";
+import { getDefinitionKind } from "../brand.js";
+import { type DiscoveryContext, displayPath } from "./context.js";
+import {
+  findModuleFile,
+  isDirectory,
+  isModuleFile,
+  toPosix,
+  walkFiles,
+} from "./fs.js";
+import { importDefault } from "./modules.js";
+
+export async function loadABs(
+  ctx: DiscoveryContext,
+  agentDir: string,
+  onDisable?: (source: string, path: string) => void
+): 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,
+      onDisable === undefined ? "ab" : ["ab", "disabled"]
+    );
+    if (definition !== undefined) {
+      if (getDefinitionKind(definition) === "disabled") {
+        onDisable?.("ab", single);
+      } else {
+        const name = resolveABName(definition, "ab");
+        seen.add(name);
+        abs.push({
+          name,
+          source: "ab",
+          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,
+        onDisable === undefined ? "ab" : ["ab", "disabled"]
+      );
+      if (definition === undefined) {
+        continue;
+      }
+      if (getDefinitionKind(definition) === "disabled") {
+        onDisable?.(stem, filePath);
+        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,
+        source: stem,
+        definition: definition as DiscoveredAB["definition"],
+      });
+    }
+  }
+
+  return abs;
+}
+
+export 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;
+  }
+}
+
+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;
+}

package/src/internal/discovery/agent-config.ts

@@ -0,0 +1,222 @@
+/**
+ * `agent/agent.ts`: model, runtime architecture, working directory, hosting, and concurrency.
+ */
+
+import { basename, isAbsolute, join, resolve } from "node:path";
+import {
+  type AgentArchitecture,
+  type AgentConcurrencyOptions,
+  type AgentConfigDefinition,
+  type AgentHostingOptions,
+  type AgentRuntime,
+  MAX_RUNNING_TURNS_LIMIT,
+  type ModelSetting,
+} from "../../types.js";
+import { normalizePositiveInt } from "../bounded-int.js";
+import {
+  isReservedSecretName,
+  MAX_EGRESS_DOMAINS,
+  validateEgressDomain,
+  validateSecretName,
+} from "../hosting.js";
+import { defaultLocalHarnessCwd, isNestedInGitRepo } from "../workspace.js";
+import { type DiscoveryContext, displayPath, isBlank } from "./context.js";
+import { findModuleFile } from "./fs.js";
+import { importDefault } from "./modules.js";
+
+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;
+}
+
+export 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. */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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;
+  }
+}
+
+export 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;
+}
+
+export 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() !== ""
+  );
+}

package/src/internal/discovery/agent.ts

@@ -0,0 +1,319 @@
+/**
+ * Compile one `agent/` directory (and its subagents) into a {@link ResolvedAgent}.
+ */
+
+import { join } from "node:path";
+import {
+  type ArtifactsDefinition,
+  DEFAULT_MODEL,
+  type DiscoveredAB,
+  type DiscoveredChannel,
+  type DiscoveredHook,
+  type DiscoveredSchedule,
+  type ResolvedAgent,
+} from "../../types.js";
+import { withIdentityPreamble } from "../workspace.js";
+import {
+  isValidModelSetting,
+  loadAgentConfig,
+  resolveAgentCwd,
+  resolveArchitecture,
+  resolveConcurrency,
+  resolveHosting,
+  resolveLocalCwd,
+  runtimeArchitectureCompatibilityError,
+} from "./agent-config.js";
+import { loadConnections, loadHostConnections } from "./connections.js";
+import { type DiscoveryContext, displayPath } from "./context.js";
+import type { ExtensionContributions } from "./extensions.js";
+import { appendExtensions } from "./extensions.js";
+import { sortedEntries } from "./fs.js";
+import { loadInstructions } from "./instructions.js";
+import {
+  checkGrokBotRuntimeLimitations,
+  resolveRuntime,
+  warnCloudRuntimeLimitations,
+} from "./runtime.js";
+import { loadSeedFiles } from "./seed-files.js";
+import { loadSkills } from "./skills.js";
+import { loadSubagent, loadSubagents } from "./subagent.js";
+import { appendBuiltinTools, loadTools } from "./tools.js";
+
+export interface LoadedRootAgent {
+  agent: ResolvedAgent;
+  projectSlots: Pick<
+    ExtensionContributions,
+    "hooks" | "channels" | "schedules" | "abs" | "artifacts"
+  >;
+}
+
+export async function loadAgent(
+  ctx: DiscoveryContext,
+  agentDir: string,
+  options: { name: string; isRoot: boolean }
+): Promise<LoadedRootAgent> {
+  if (!options.isRoot) {
+    return {
+      agent: await loadSubagent(ctx, agentDir, options.name),
+      projectSlots: {
+        hooks: [],
+        channels: [],
+        schedules: [],
+        abs: [],
+        artifacts: undefined,
+      },
+    };
+  }
+  const config = await loadAgentConfig(ctx, agentDir, options.isRoot);
+  const name = config?.name ?? options.name;
+  const authoredInstructions = await loadInstructions(
+    ctx,
+    agentDir,
+    config,
+    options.isRoot
+  );
+
+  const tools = await loadTools(ctx, join(agentDir, "tools"));
+  const skills = await loadSkills(ctx, join(agentDir, "skills"));
+  const connections = await loadConnections(
+    ctx,
+    join(agentDir, "mcp-connections")
+  );
+  const subagents = await loadSubagents(ctx, join(agentDir, "subagents"));
+  const hostConnections = await loadHostConnections(ctx, agentDir, connections);
+  const seedFiles = await loadSeedFiles(ctx, agentDir);
+  const hooks: DiscoveredHook[] = [];
+  const channels: DiscoveredChannel[] = [];
+  const schedules: DiscoveredSchedule[] = [];
+  const abs: DiscoveredAB[] = [];
+  const instructionParts: string[] = [];
+  const contributions = {
+    tools,
+    skills,
+    connections,
+    hostConnections,
+    subagents,
+    hooks,
+    channels,
+    schedules,
+    instructionParts,
+    seedFiles,
+    abs,
+    artifacts: undefined as ArtifactsDefinition | undefined,
+  };
+  const extensions = await appendExtensions(
+    ctx,
+    join(agentDir, "extensions"),
+    contributions
+  );
+  const promptParts = [...instructionParts];
+  if (authoredInstructions !== undefined && authoredInstructions !== "") {
+    promptParts.unshift(authoredInstructions);
+  }
+  const prompt = promptParts.join("\n\n");
+  // Root agents without authored instructions stay undefined (diagnostic
+  // already recorded) unless an extension contributed a fragment.
+  const instructions =
+    prompt === "" ? undefined : withIdentityPreamble(name, prompt);
+  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 {
+    agent: {
+      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,
+    },
+    projectSlots: {
+      hooks,
+      channels,
+      schedules,
+      abs,
+      artifacts: contributions.artifacts,
+    },
+  };
+}
+
+export async function warnUnknownSlots(
+  ctx: DiscoveryContext,
+  agentDir: string
+): Promise<void> {
+  const known = new Set([
+    "agent",
+    "instructions",
+    "tools",
+    "skills",
+    "extensions",
+    "mcp-connections",
+    "host-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).`,
+    });
+  }
+}