@cursor/july 0.1.100 → 0.1.102

package/src/internal/conversation-mirror.ts

@@ -37,16 +37,13 @@
  */
 
 import type { LocalAgentDocument, LocalAgentStore } from "@cursor/sdk";
-import { agentStoreKeys, type FileSink } from "../files.js";
-import {
-  cursorFrameworkStoreSourceId,
-  cursorHostedFiles,
-} from "../files-backends/cursor-hosted.js";
+import { agentSdkAgentStoreKeys, type FileSink } from "../files.js";
+import { cursorHostedFiles } from "../files-backends/cursor-hosted.js";
 import type { AgentProject } from "../types.js";
 import { mapBounded } from "./bounded.js";
 import { resolveApiKeySync } from "./cursor/credentials.js";
-import { AGENT_SERVE_GENERATION_ENV_VAR } from "./cursor-relay-core.js";
 import { describeError } from "./describe-error.js";
+import { resolveAgentV2Hosting } from "./v2-hosting.js";
 
 /**
  * Persist/restore one SDK conversation between a {@link LocalAgentStore} and
@@ -70,7 +67,7 @@ export interface ConversationMirror {
   persist(store: LocalAgentStore, sdkAgentId: string): Promise<void>;
 }
 
-/** Wire shape at {@link agentStoreKeys.conversationManifest}. */
+/** Wire shape at {@link agentSdkAgentStoreKeys.conversationManifest}. */
 interface ConversationManifestV1 {
   v: 1;
   /** The SDK agent document, verbatim apart from `activeRunId` (nulled). */
@@ -181,7 +178,11 @@ export function createConversationMirror(
             continue;
           }
           await sink.put(
-            agentStoreKeys.conversationBlob(agentName, sdkAgentId, blobId),
+            agentSdkAgentStoreKeys.conversationBlob(
+              agentName,
+              sdkAgentId,
+              blobId
+            ),
             bytes
           );
           // Content-addressed: once in the sink, never re-uploaded.
@@ -197,7 +198,7 @@ export function createConversationMirror(
         };
         // Manifest last: it only ever references blobs already uploaded.
         await sink.put(
-          agentStoreKeys.conversationManifest(agentName, sdkAgentId),
+          agentSdkAgentStoreKeys.conversationManifest(agentName, sdkAgentId),
           new TextEncoder().encode(JSON.stringify(manifest))
         );
       });
@@ -242,7 +243,11 @@ export function createConversationMirror(
           async (blobId) => ({
             blobId,
             body: await sink.get(
-              agentStoreKeys.conversationBlob(agentName, sdkAgentId, blobId)
+              agentSdkAgentStoreKeys.conversationBlob(
+                agentName,
+                sdkAgentId,
+                blobId
+              )
             ),
           })
         );
@@ -317,7 +322,7 @@ async function readManifest(
   sdkAgentId: string
 ): Promise<ManifestRead> {
   const body = await sink.get(
-    agentStoreKeys.conversationManifest(agentName, sdkAgentId)
+    agentSdkAgentStoreKeys.conversationManifest(agentName, sdkAgentId)
   );
   if (body === undefined) {
     return { outcome: "miss" };
@@ -379,17 +384,17 @@ export function selectConversationMirror(input: {
   logger?: (line: string) => void;
   env?: Record<string, string | undefined>;
 }): ConversationMirror | undefined {
-  if (input.project.agent.architecture !== "v2") {
-    return undefined;
-  }
-  const env = input.env ?? process.env;
-  if (env[AGENT_SERVE_GENERATION_ENV_VAR] === undefined) {
+  const hosting = resolveAgentV2Hosting({
+    architecture: input.project.agent.architecture,
+    env: input.env as NodeJS.ProcessEnv | undefined,
+  });
+  if (hosting.kind !== "cursor-managed") {
     return undefined;
   }
-  const envSnapshot = env as NodeJS.ProcessEnv;
   return createConversationMirror({
     sink: cursorHostedFiles({
-      resolveStoreSourceId: () => cursorFrameworkStoreSourceId(envSnapshot),
+      resolveStoreSourceId: () =>
+        hosting.resolveStoreIds().frameworkStoreSourceId,
       // Full chain (env → key file → stored login): frozen engines listen
       // unsigned and bind CURSOR_API_KEY_FILE at task time, after this sink
       // is constructed.

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-deployment-secrets.ts

@@ -0,0 +1,72 @@
+/**
+ * Task-time application secrets for hosted v2 freeze restores.
+ *
+ * The deployment host rewrites this tmpfs document before each admission and
+ * execution request. July reloads it synchronously because the process was
+ * already running in the frozen snapshot when the task-specific values
+ * arrived.
+ */
+
+import { readFileSync } from "node:fs";
+
+export const DEFAULT_AGENT_SERVE_DEPLOYMENT_SECRETS_FILE =
+  "/run/cursor/secrets/AGENT_SERVE_DEPLOYMENT_SECRETS.json";
+
+const SECRET_NAME_PATTERN = /^[A-Z][A-Z0-9_]{0,63}$/;
+const appliedSecretNames = new Set<string>();
+
+function parseBoundSecrets(path: string): Record<string, string> | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return undefined;
+  }
+  if (parsed === null || typeof parsed !== "object") {
+    return undefined;
+  }
+  const envelope = parsed as { v?: unknown; secrets?: unknown };
+  if (
+    envelope.v !== 1 ||
+    envelope.secrets === null ||
+    typeof envelope.secrets !== "object" ||
+    Array.isArray(envelope.secrets)
+  ) {
+    return undefined;
+  }
+  const secrets: Record<string, string> = {};
+  for (const [name, value] of Object.entries(envelope.secrets)) {
+    if (
+      SECRET_NAME_PATTERN.test(name) &&
+      !name.startsWith("CURSOR_") &&
+      typeof value === "string"
+    ) {
+      secrets[name] = value;
+    }
+  }
+  return secrets;
+}
+
+/**
+ * Refresh `process.env` from the latest bound document. A missing or malformed
+ * file is a no-op; an empty valid document removes values loaded by an earlier
+ * bind after the deployment secret was unset.
+ */
+export function refreshBoundDeploymentSecrets(
+  path: string = DEFAULT_AGENT_SERVE_DEPLOYMENT_SECRETS_FILE
+): void {
+  const secrets = parseBoundSecrets(path);
+  if (secrets === undefined) {
+    return;
+  }
+  for (const name of appliedSecretNames) {
+    if (!(name in secrets)) {
+      delete process.env[name];
+    }
+  }
+  appliedSecretNames.clear();
+  for (const [name, value] of Object.entries(secrets)) {
+    process.env[name] = value;
+    appliedSecretNames.add(name);
+  }
+}

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/cursor-deployment-relay.ts

@@ -33,17 +33,33 @@ interface SubscriptionStatus {
   detail?: string;
 }
 
+export type DeploymentSubscriptionSource =
+  | readonly ResolvedSubscription[]
+  | (() => readonly ResolvedSubscription[]);
+
 export interface DeploymentEventRelayOptions {
   baseUrl: string;
   apiKey: string;
   stateDir: string;
-  subscriptions: readonly ResolvedSubscription[];
+  /**
+   * Snapshot or a getter. A getter is re-read on every registration
+   * heartbeat so a channel that refreshes `deploySourceUris` after start
+   * can add sources without restarting the relay.
+   */
+  subscriptions: DeploymentSubscriptionSource;
   dispatch: (event: DeploymentEvent) => Promise<void>;
   logger: (line: string) => void;
   fetchImpl?: typeof fetch;
   pollWaitMs?: number;
 }
 
+/** Current subscriptions: a live getter, otherwise the snapshot. */
+export function currentDeploymentSubscriptions(
+  subscriptions: DeploymentSubscriptionSource
+): readonly ResolvedSubscription[] {
+  return typeof subscriptions === "function" ? subscriptions() : subscriptions;
+}
+
 /** Normalize the channel's `deploySourceUris` option into concrete subscriptions. */
 export function resolveDeploymentSubscriptions(options: {
   deploySourceUris: readonly (string | DeploymentSubscription)[];
@@ -90,10 +106,46 @@ export function resolveDeploymentSubscriptions(options: {
         ? []
         : [...new Set([...existing.environments, ...environments])];
   }
-  // Empty is legal here and means "this channel wants nothing", which is how
-  // an env-configured channel stays inert without a deploy-source list. The
-  // wire-level empty list means deregister, so the host simply never
-  // registers it.
+  // Empty is legal here and means "this channel wants nothing". The
+  // wire-level empty list means deregister. The host re-resolves on each
+  // heartbeat, so a channel that later fills `deploySourceUris` can
+  // register without a restart.
+  return [...bySource.values()];
+}
+
+/**
+ * Union per-channel subscriptions, widening events and environments when
+ * the same deploy source appears more than once. An empty environment
+ * list means every environment and absorbs a narrower list.
+ */
+export function mergeResolvedSubscriptions(
+  groups: readonly (readonly ResolvedSubscription[])[]
+): ResolvedSubscription[] {
+  const bySource = new Map<string, ResolvedSubscription>();
+  for (const group of groups) {
+    for (const subscription of group) {
+      const existing = bySource.get(subscription.deploySourceUri);
+      if (existing === undefined) {
+        bySource.set(subscription.deploySourceUri, {
+          deploySourceUri: subscription.deploySourceUri,
+          environments: [...subscription.environments],
+          events: new Set(subscription.events),
+        });
+        continue;
+      }
+      for (const event of subscription.events) existing.events.add(event);
+      existing.environments =
+        existing.environments.length === 0 ||
+        subscription.environments.length === 0
+          ? []
+          : [
+              ...new Set([
+                ...existing.environments,
+                ...subscription.environments,
+              ]),
+            ];
+    }
+  }
   return [...bySource.values()];
 }
 
@@ -176,7 +228,9 @@ export class DeploymentEventRelay {
       pollPath: "/v0/deployment-events",
       buildRegistrationBody: (consumerId) => ({
         consumerId,
-        subscriptions: options.subscriptions.map((subscription) => ({
+        subscriptions: currentDeploymentSubscriptions(
+          options.subscriptions
+        ).map((subscription) => ({
           deploySourceUri: subscription.deploySourceUri,
           environments: subscription.environments,
           events: [...subscription.events],
@@ -190,12 +244,15 @@ export class DeploymentEventRelay {
       }),
       applyRegistrationResponse: (json) => {
         const result = json as { deploySourceUris?: SubscriptionStatus[] };
+        const wantedSubscriptions = currentDeploymentSubscriptions(
+          options.subscriptions
+        );
         this.subscribed = new Map();
         this.loggedSkippedSources.clear();
         const lines: string[] = [];
         const confirmed: string[] = [];
         for (const status of result.deploySourceUris ?? []) {
-          const wanted = options.subscriptions.find(
+          const wanted = wantedSubscriptions.find(
             (subscription) =>
               subscription.deploySourceUri === status.deploySourceUri
           );
@@ -210,7 +267,7 @@ export class DeploymentEventRelay {
         }
         if (confirmed.length > 0) {
           const kinds = [
-            ...new Set(options.subscriptions.flatMap((s) => [...s.events])),
+            ...new Set(wantedSubscriptions.flatMap((s) => [...s.events])),
           ];
           lines.push(
             `subscribed to ${confirmed.join(", ")} for events: ${kinds.join(", ")}`

package/src/internal/deploy-client.ts

@@ -267,6 +267,8 @@ export interface AgentkitDeployStatus {
    * Absent on control planes that predate the field.
    */
   repositories?: string[];
+  /** Names of application-scoped secrets (values are never returned). */
+  secretNames?: string[];
 }
 
 export const TERMINAL_AGENTKIT_DEPLOY_STATUSES: ReadonlySet<AgentkitCustomerStatus> =
@@ -359,6 +361,7 @@ const agentkitDeployStatusSchema = z
     statusMessage: z.string().nullable(),
     // Optional: backends that predate the v2 bake-failure column omit it.
     lastError: z.string().nullable().optional(),
+    secretNames: z.array(z.string()).optional(),
   })
   .passthrough();
 
@@ -740,24 +743,7 @@ export class AgentServeDeployClient {
     slug: string;
     secrets: Array<{ name: string; value: string }>;
   }): Promise<string[]> {
-    for (const { name, value } of args.secrets) {
-      const nameError = validateSettableSecretName(name);
-      if (nameError !== undefined) {
-        throw new DeployApiError(nameError, 400);
-      }
-      if (Buffer.byteLength(value, "utf8") > MAX_SECRET_VALUE_BYTES) {
-        throw new DeployApiError(
-          `The value for ${name} is too large (max ${MAX_SECRET_VALUE_BYTES} bytes).`,
-          400
-        );
-      }
-    }
-    if (args.secrets.length > MAX_SECRETS) {
-      throw new DeployApiError(
-        `Too many secrets in one request (${args.secrets.length}); deployments hold at most ${MAX_SECRETS}.`,
-        400
-      );
-    }
+    this.validateSecrets(args.secrets);
     const raw = await this.request({
       method: "PUT",
       path: `/internal/agent-serve/deployments/${encodeURIComponent(args.slug)}/secrets`,
@@ -767,6 +753,22 @@ export class AgentServeDeployClient {
     return setSecretsResponseSchema.parse(raw).secretNames;
   }
 
+  /** Upsert application-scoped secrets on an AgentSDK v2 deployment. */
+  async setAgentkitSecrets(args: {
+    teamId: number;
+    slug: string;
+    secrets: Array<{ name: string; value: string }>;
+  }): Promise<string[]> {
+    this.validateSecrets(args.secrets);
+    const raw = await this.request({
+      method: "PUT",
+      path: `/internal/agentsdk/deployments/${encodeURIComponent(args.slug)}/secrets`,
+      body: { teamId: args.teamId, secrets: args.secrets },
+      context: { verb: "set secrets", slug: args.slug },
+    });
+    return setSecretsResponseSchema.parse(raw).secretNames;
+  }
+
   /** Secret names + creation times; values are never returned. */
   async listSecrets(args: {
     teamId: number;
@@ -780,6 +782,19 @@ export class AgentServeDeployClient {
     return listSecretsResponseSchema.parse(raw).secrets;
   }
 
+  /** Secret names + creation times for an AgentSDK v2 application. */
+  async listAgentkitSecrets(args: {
+    teamId: number;
+    slug: string;
+  }): Promise<SecretInfo[]> {
+    const raw = await this.request({
+      method: "GET",
+      path: `/internal/agentsdk/deployments/${encodeURIComponent(args.slug)}/secrets?teamId=${args.teamId}`,
+      context: { verb: "list secrets", slug: args.slug },
+    });
+    return listSecretsResponseSchema.parse(raw).secrets;
+  }
+
   /** Remove one secret by name; 404 when it is not set. */
   async deleteSecret(args: {
     teamId: number;
@@ -797,6 +812,46 @@ export class AgentServeDeployClient {
     });
   }
 
+  /** Remove one application-scoped secret from an AgentSDK v2 deployment. */
+  async deleteAgentkitSecret(args: {
+    teamId: number;
+    slug: string;
+    name: string;
+  }): Promise<void> {
+    const nameError = validateSettableSecretName(args.name);
+    if (nameError !== undefined) {
+      throw new DeployApiError(nameError, 400);
+    }
+    await this.request({
+      method: "DELETE",
+      path: `/internal/agentsdk/deployments/${encodeURIComponent(args.slug)}/secrets/${encodeURIComponent(args.name)}?teamId=${args.teamId}`,
+      context: { verb: "unset secret", slug: args.slug },
+    });
+  }
+
+  private validateSecrets(
+    secrets: Array<{ name: string; value: string }>
+  ): void {
+    for (const { name, value } of secrets) {
+      const nameError = validateSettableSecretName(name);
+      if (nameError !== undefined) {
+        throw new DeployApiError(nameError, 400);
+      }
+      if (Buffer.byteLength(value, "utf8") > MAX_SECRET_VALUE_BYTES) {
+        throw new DeployApiError(
+          `The value for ${name} is too large (max ${MAX_SECRET_VALUE_BYTES} bytes).`,
+          400
+        );
+      }
+    }
+    if (secrets.length > MAX_SECRETS) {
+      throw new DeployApiError(
+        `Too many secrets in one request (${secrets.length}); deployments hold at most ${MAX_SECRETS}.`,
+        400
+      );
+    }
+  }
+
   /**
    * Rotate the deployment's pod credential. Returns the masked new key —
    * the raw key is injected into the pod on the next deploy, never

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;
+}