@cursor/july 0.1.101 → 0.1.102

package/src/internal/cursor/backend-client.ts

@@ -2,7 +2,8 @@
  * Minimal Connect-JSON client for the handful of `aiserver.v1.DashboardService`
  * RPCs agent-serve needs — `GetMe`, `ListSandMcpTools`, `ExecuteSandMcpTool`,
  * and the login-time key lifecycle (`CreateUserApiKey`, `ListUserApiKeys`,
- * `RevokeUserApiKey`).
+ * `RevokeUserApiKey`) — plus {@link CursorBackendClient.serviceRpc} for the
+ * odd unary call on another `aiserver.v1` service under the same token.
  *
  * Plain `fetch` POSTs with proto-JSON bodies and zod-validated responses:
  * agent-serve is a published package and should not pull the generated
@@ -25,7 +26,7 @@ import {
 } from "./session-token.js";
 
 const CLIENT_VERSION = "agent-serve-0.1.0";
-const SERVICE_PREFIX = "/aiserver.v1.DashboardService";
+const DASHBOARD_SERVICE = "DashboardService";
 const LIST_TIMEOUT_MS = 60_000;
 /** Backend-executed tools call out to third-party servers; be generous. */
 const EXECUTE_TIMEOUT_MS = 120_000;
@@ -235,9 +236,10 @@ export interface AccountMcpCallResult {
 // ============================================================================
 
 /** One DashboardService Connect-JSON POST; auth is the caller's bearer. */
-async function dashboardRpc(args: {
+async function connectRpc(args: {
   fetchImpl: typeof fetch;
   backendUrl: string;
+  service: string;
   method: string;
   bearer: string;
   body: unknown;
@@ -246,7 +248,7 @@ async function dashboardRpc(args: {
 }): Promise<Response> {
   try {
     return await args.fetchImpl(
-      `${args.backendUrl}${SERVICE_PREFIX}/${args.method}`,
+      `${args.backendUrl}/aiserver.v1.${args.service}/${args.method}`,
       {
         method: "POST",
         headers: {
@@ -485,20 +487,36 @@ export class CursorBackendClient {
     return githubTokenResponseSchema.parse(parsed);
   }
 
+  /**
+   * One unary Connect-JSON call on `aiserver.v1.<service>` with the same
+   * token exchange and 401 retry as the dashboard RPCs. Callers parse the
+   * proto-JSON response themselves.
+   */
+  serviceRpc(
+    service: string,
+    method: string,
+    body: unknown,
+    timeoutMs: number = LIST_TIMEOUT_MS
+  ): Promise<unknown> {
+    return this.rpc(method, body, timeoutMs, { service });
+  }
+
   private async rpc(
     method: string,
     body: unknown,
     timeoutMs = LIST_TIMEOUT_MS,
-    options?: { teamId?: number }
+    options?: { teamId?: number; service?: string }
   ): Promise<unknown> {
+    const service = options?.service ?? DASHBOARD_SERVICE;
     const extraHeaders =
       options?.teamId === undefined
         ? undefined
         : { "x-cursor-team-id": String(options.teamId) };
     const bearer = await this.getAccessToken();
-    const first = await dashboardRpc({
+    const first = await connectRpc({
       fetchImpl: this.fetchImpl,
       backendUrl: this.backendUrl,
+      service,
       method,
       bearer,
       body,
@@ -516,9 +534,10 @@ export class CursorBackendClient {
       this.token = undefined;
     }
     const retryBearer = await this.getAccessToken();
-    const second = await dashboardRpc({
+    const second = await connectRpc({
       fetchImpl: this.fetchImpl,
       backendUrl: this.backendUrl,
+      service,
       method,
       bearer: retryBearer,
       body,
@@ -612,11 +631,12 @@ export async function createUserApiKeyWithSessionToken(args: {
   keyName: string;
   fetchImpl?: typeof fetch;
 }): Promise<string> {
-  const response = await dashboardRpc({
+  const response = await connectRpc({
     fetchImpl: args.fetchImpl ?? fetch,
     backendUrl: args.backendUrl.endsWith("/")
       ? args.backendUrl.slice(0, -1)
       : args.backendUrl,
+    service: DASHBOARD_SERVICE,
     method: "CreateUserApiKey",
     bearer: args.sessionToken,
     body: { name: args.keyName },
@@ -666,9 +686,10 @@ export async function revokeMintedUserApiKey(args: {
     ? args.backendUrl.slice(0, -1)
     : args.backendUrl;
 
-  const listResponse = await dashboardRpc({
+  const listResponse = await connectRpc({
     fetchImpl,
     backendUrl,
+    service: DASHBOARD_SERVICE,
     method: "ListUserApiKeys",
     bearer: args.sessionToken,
     body: {},
@@ -686,9 +707,10 @@ export async function revokeMintedUserApiKey(args: {
     // lagging replica — skip rather than touch any other key.
     return;
   }
-  const revokeResponse = await dashboardRpc({
+  const revokeResponse = await connectRpc({
     fetchImpl,
     backendUrl,
+    service: DASHBOARD_SERVICE,
     method: "RevokeUserApiKey",
     bearer: args.sessionToken,
     body: { id: match.id },

package/src/internal/cursor/hosted-store-secrets.ts

@@ -70,3 +70,30 @@ export function resolveFrameworkStoreSourceIdSync(
     env
   );
 }
+
+export type CursorManagedV2StoreIds = {
+  deploymentStoreSourceId: string;
+  frameworkStoreSourceId: string;
+};
+
+/**
+ * Resolve the complete managed-v2 store identity at the process boundary.
+ *
+ * Freeze snapshots construct storage before task bind, so callers keep this
+ * resolver lazy. Once an operation needs storage, both ids are mandatory.
+ */
+export function requireCursorManagedV2StoreIdsSync(
+  env: NodeJS.ProcessEnv = process.env
+): CursorManagedV2StoreIds {
+  const deploymentStoreSourceId = resolveDeploymentStoreSourceIdSync(env);
+  const frameworkStoreSourceId = resolveFrameworkStoreSourceIdSync(env);
+  if (
+    deploymentStoreSourceId === undefined ||
+    frameworkStoreSourceId === undefined
+  ) {
+    throw new Error(
+      "Cursor-managed AgentSDK v2 requires AGENT_SERVE_STORE_SOURCE_ID and AGENT_SERVE_FRAMEWORK_STORE_SOURCE_ID"
+    );
+  }
+  return { deploymentStoreSourceId, frameworkStoreSourceId };
+}

package/src/internal/discovery/ab.ts

@@ -0,0 +1,111 @@
+/**
+ * `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 { 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
+): 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;
+}
+
+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() !== ""
+  );
+}