@cursor/july 0.1.101 → 0.1.103

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
@@ -16,6 +17,8 @@
 import { randomUUID } from "node:crypto";
 import { z } from "zod";
 import type { McpToolAnnotations } from "../../types.js";
+import { describeError } from "../describe-error.js";
+import { CLI_COMMAND_NAME as CLI } from "../distribution.js";
 import { boundedToolAnnotations } from "../mcp-host.js";
 import {
   CURSOR_SESSION_EXCHANGE_PATH,
@@ -25,7 +28,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 +238,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 +250,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: {
@@ -298,9 +302,10 @@ export interface CursorBackendClientOptions {
   backendUrl: string;
   apiKey: string;
   /**
-   * Re-read the key on each authenticated call. Hosted freeze listens
-   * unsigned and the binder drops the key after restore; a constructor-frozen
-   * key would miss that bind.
+   * Re-resolve the key on each authenticated call. Hosted freeze listens
+   * unsigned and only gains a credential at task time (hosted deliveries
+   * consume the bind file into `CURSOR_API_KEY` before authored work); a
+   * constructor-frozen key would miss that bind.
    */
   getApiKey?: () => string;
   logger?: (line: string) => void;
@@ -485,20 +490,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 +537,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,
@@ -588,7 +610,7 @@ export class CursorBackendClient {
         }
         throw new CursorBackendError(
           error.status === 401
-            ? "The Cursor API key was rejected. Run `agent-serve login` again or update CURSOR_API_KEY."
+            ? `The Cursor API key was rejected. Run \`${CLI} login\` again or update CURSOR_API_KEY.`
             : `Cursor API key exchange failed (${error.status}).`,
           error.status
         );
@@ -604,7 +626,7 @@ export class CursorBackendClient {
 
 /**
  * Mint a named user API key from a short-lived login session token. Used
- * exactly once per `agent-serve login`; the session token is then discarded.
+ * exactly once per `agent-sdk login`; the session token is then discarded.
  */
 export async function createUserApiKeyWithSessionToken(args: {
   backendUrl: string;
@@ -612,11 +634,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 +689,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 +710,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 },
@@ -845,7 +870,7 @@ function describeGithubTokenHttpFailure(
   if (status === 401) {
     return `The Cursor API key was rejected${
       detail === undefined ? "" : `: ${detail}`
-    }. Run \`agent-serve login\` again or update CURSOR_API_KEY.`;
+    }. Run \`${CLI} login\` again or update CURSOR_API_KEY.`;
   }
   if (detail !== undefined) {
     return detail;
@@ -877,10 +902,6 @@ function retryAfterMsFromResponse(response: Response): number | undefined {
   return Math.min(retryAfter * 1000, MAX_GITHUB_TOKEN_RETRY_AFTER_MS);
 }
 
-function describeError(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
-
 /** Release undici/fetch connection slots on responses we will not parse. */
 async function drainResponseBody(response: Response): Promise<void> {
   try {

package/src/internal/cursor/bound-secret-file.ts

@@ -0,0 +1,108 @@
+/**
+ * Destroying a hosted v2 task-bind secret file after its value is in
+ * `process.env`.
+ *
+ * The bind files under `/run/cursor/secrets/` are an IPC channel, not a
+ * credential store: the control plane cannot set another process's
+ * environment, so it drops the value on tmpfs and July copies it into
+ * `process.env` before anything authored runs. Once that copy succeeds the
+ * on-disk value is pure liability — authored agent code runs in this pod and
+ * can read any world-readable path.
+ *
+ * Unlink is preferred. It is not always available: pod-daemon writes the
+ * files as root, and removing a directory entry needs write permission on
+ * `/run/cursor/secrets`, which is root-owned. Making that directory writable
+ * by the guest is not the fix — untrusted guest code could then plant a
+ * symlink that the next root-side bind write would follow. The binder instead
+ * relaxes the two secret files themselves so the guest can truncate them, and
+ * this module falls back to a zero-length overwrite. Both readers treat an
+ * empty bind file as unsigned.
+ */
+
+import {
+  closeSync,
+  fsyncSync,
+  ftruncateSync,
+  openSync,
+  readFileSync,
+  unlinkSync,
+} from "node:fs";
+
+/**
+ * What happened to a bind file. Only `readable` is a failure: the secret
+ * survived the consume and callers must not run authored code.
+ */
+export type BoundSecretFileDisposal =
+  /** Nothing recoverable was there — missing, empty, or unreadable already. */
+  | { state: "absent" }
+  /** Directory entry removed. */
+  | { state: "unlinked" }
+  /** Truncated to zero length and fsynced; an empty file remains. */
+  | { state: "wiped" }
+  /** Still recoverable by a later `readFile`. */
+  | { state: "readable"; reason: string };
+
+/**
+ * Whether a later `readFile` of this path could still recover a secret.
+ * A read failure counts as unrecoverable: this process just read the file
+ * during hydrate, so losing access to it means the content is gone.
+ */
+export function boundSecretFileIsReadable(path: string): boolean {
+  try {
+    return readFileSync(path, "utf8").trim() !== "";
+  } catch {
+    return false;
+  }
+}
+
+function errorReason(error: unknown): string {
+  const code = (error as { code?: unknown } | undefined)?.code;
+  return typeof code === "string" ? code : "unknown";
+}
+
+/**
+ * Remove a bind file's contents from disk, preferring unlink over an empty
+ * leftover. Callers must have already copied the value into `process.env`:
+ * this is destructive and there is no second bind until the control plane
+ * rewrites the file before the next hosted request.
+ */
+export function destroyBoundSecretFile(path: string): BoundSecretFileDisposal {
+  if (!boundSecretFileIsReadable(path)) {
+    // Nothing recoverable, so nothing to fail over. Still try to clear the
+    // empty leftover: whether that succeeds does not change the disposal,
+    // because there is no secret here either way.
+    try {
+      unlinkSync(path);
+    } catch {
+      // Already gone, or a directory the guest cannot write. Both are fine.
+    }
+    return { state: "absent" };
+  }
+  let unlinkReason: string | undefined;
+  try {
+    unlinkSync(path);
+    if (!boundSecretFileIsReadable(path)) {
+      return { state: "unlinked" };
+    }
+    unlinkReason = "recreated";
+  } catch (error) {
+    unlinkReason = errorReason(error);
+  }
+  try {
+    const fd = openSync(path, "r+");
+    try {
+      ftruncateSync(fd, 0);
+      fsyncSync(fd);
+    } finally {
+      closeSync(fd);
+    }
+  } catch (error) {
+    return {
+      state: "readable",
+      reason: `unlink ${unlinkReason}, truncate ${errorReason(error)}`,
+    };
+  }
+  return boundSecretFileIsReadable(path)
+    ? { state: "readable", reason: `unlink ${unlinkReason}, truncate no-op` }
+    : { state: "wiped" };
+}

package/src/internal/cursor/credentials.ts

@@ -4,13 +4,16 @@
  * Exactly one kind of secret exists at runtime: a **personal Cursor user API
  * key**. Two ways to obtain it, one code path after that:
  *
- * - `agent-serve login` runs the same PKCE browser flow as `cursor-agent`
+ * - `agent-sdk login` runs the same PKCE browser flow as `cursor-agent`
  *   and Sand, then uses the short-lived session once to mint a named,
  *   dashboard-revocable user API key — only the key is stored.
  * - `CURSOR_API_KEY` (or `serve({ apiKey })`) wins over the stored key, so
  *   CI and hosted deployments stay env-driven.
  * - `CURSOR_API_KEY_FILE` (or the hosted default path) is next: freeze bind
- *   drops the key at task time without restarting July.
+ *   drops the key at task time without restarting July. On the hosted path
+ *   that file is consumed into `CURSOR_API_KEY` and destroyed before
+ *   anything authored runs, so this fallback is there for local,
+ *   self-hosted, and the unsigned window before the first bind.
  * - Stored `july login` is last. Same order for hosted and self-hosted:
  *   option → env → file → login.
  *
@@ -26,6 +29,10 @@ import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { z } from "zod";
 import { CLI_COMMAND_NAME } from "../distribution.js";
+import {
+  type BoundSecretFileDisposal,
+  destroyBoundSecretFile,
+} from "./bound-secret-file.js";
 
 export const DEFAULT_CURSOR_BACKEND_URL = "https://api2.cursor.sh";
 export const DEFAULT_CURSOR_EXTERNAL_API_URL = "https://api.cursor.com";
@@ -182,9 +189,11 @@ export interface ResolvedApiKey {
 
 /**
  * Hosted task-bind path. Not a secret: the snapshot may name this path.
- * The binder writes the key here after restore; July re-reads on each use.
- * Override with `CURSOR_API_KEY_FILE`. A missing file is unsigned — self-hosted
- * then uses `CURSOR_API_KEY` or stored login.
+ * The binder writes the key here after restore, and hosted admission /
+ * execution consume it into `process.env.CURSOR_API_KEY` and destroy the
+ * file before authored work — this is an IPC handoff, not a credential
+ * source July keeps reading. Override with `CURSOR_API_KEY_FILE`. A missing
+ * file is unsigned — self-hosted then uses `CURSOR_API_KEY` or stored login.
  */
 export const DEFAULT_CURSOR_API_KEY_FILE: string =
   "/run/cursor/secrets/CURSOR_API_KEY";
@@ -195,12 +204,18 @@ export const DEFAULT_CURSOR_API_KEY_FILE: string =
  * listens before the binder drops the key; self-hosted falls through to
  * env or login.
  */
+export function resolveCursorApiKeyFilePath(
+  filePath?: string,
+  env: NodeJS.ProcessEnv = process.env
+): string {
+  const configured = filePath ?? env.CURSOR_API_KEY_FILE;
+  return configured !== undefined && configured.trim() !== ""
+    ? configured.trim()
+    : DEFAULT_CURSOR_API_KEY_FILE;
+}
+
 export function readApiKeyFromFile(filePath?: string): string | undefined {
-  const configured = filePath ?? process.env.CURSOR_API_KEY_FILE;
-  const path =
-    configured !== undefined && configured.trim() !== ""
-      ? configured.trim()
-      : DEFAULT_CURSOR_API_KEY_FILE;
+  const path = resolveCursorApiKeyFilePath(filePath);
   try {
     const raw = readFileSync(path, "utf8").trim();
     return raw === "" ? undefined : raw;
@@ -209,6 +224,56 @@ export function readApiKeyFromFile(filePath?: string): string | undefined {
   }
 }
 
+export type BoundCursorApiKeyConsumeResult = {
+  /** The file supplied `CURSOR_API_KEY` on this call. */
+  applied: boolean;
+  disposal: BoundSecretFileDisposal;
+};
+
+/**
+ * Copy the task-bind key file into `process.env.CURSOR_API_KEY`, then destroy
+ * the file.
+ *
+ * Hosted v2 cannot set another process's environment from the binder, so it
+ * drops a tmpfs file. Teaching every reader to open that file misses authored
+ * `process.env.CURSOR_API_KEY` and leaves a secret on disk. Hosted admission /
+ * execution call this once per request, next to the deployment-secrets
+ * consume: after it returns, env-only readers work and the key is no longer
+ * recoverable from disk. The control plane re-binds before the next request.
+ *
+ * The env write always happens before the destroy, never the other way round.
+ * An already-set `CURSOR_API_KEY` is not overwritten, but the file is still
+ * destroyed — env is the source, the file is only the handoff.
+ *
+ * A `readable` disposal means the secret survived; callers on the hosted path
+ * must fail the request rather than run authored code.
+ */
+export function consumeBoundCursorApiKey(options?: {
+  filePath?: string;
+  env?: NodeJS.ProcessEnv;
+}): BoundCursorApiKeyConsumeResult {
+  const env = options?.env ?? process.env;
+  const path = resolveCursorApiKeyFilePath(options?.filePath, env);
+  const envKeyAlreadySet =
+    env.CURSOR_API_KEY !== undefined && env.CURSOR_API_KEY.trim() !== "";
+  let raw = "";
+  try {
+    raw = readFileSync(path, "utf8").trim();
+  } catch {
+    return { applied: false, disposal: { state: "absent" } };
+  }
+  if (raw === "") {
+    return { applied: false, disposal: destroyBoundSecretFile(path) };
+  }
+  if (!envKeyAlreadySet) {
+    env.CURSOR_API_KEY = raw;
+  }
+  return {
+    applied: !envKeyAlreadySet,
+    disposal: destroyBoundSecretFile(path),
+  };
+}
+
 /**
  * First present source wins. We define the order; operators do not.
  * `--api-key` / `serve({ apiKey })` → `CURSOR_API_KEY` → `CURSOR_API_KEY_FILE`

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

@@ -0,0 +1,75 @@
+/**
+ * The hosted v2 per-request secret handoff: bind files in, `process.env` out,
+ * nothing recoverable left on disk.
+ *
+ * The control plane rewrites `/run/cursor/secrets/` before every hosted
+ * admission and execution because it cannot set the already-running July
+ * process's environment. This module closes that handoff at the top of each
+ * request: copy both documents into `process.env`, then destroy them. Hosted
+ * request code and authored agents read env from there on — nothing on the
+ * hosted path should open these paths again.
+ *
+ * It fails closed. A secret that survives the consume would sit world-readable
+ * next to authored agent code for the length of a turn, so the caller returns
+ * a retryable error instead of dispatching. The next request re-binds and
+ * consumes again.
+ */
+
+import {
+  consumeBoundCursorApiKey,
+  DEFAULT_CURSOR_API_KEY_FILE,
+} from "./credentials.js";
+import {
+  consumeBoundDeploymentSecrets,
+  DEFAULT_AGENT_SERVE_DEPLOYMENT_SECRETS_FILE,
+} from "./hosted-deployment-secrets.js";
+
+/** Wire error code for a bind file that outlived its consume. */
+export const BOUND_SECRETS_NOT_CONSUMED = "bound_secrets_not_consumed";
+
+export type HostedBoundSecretsResult =
+  | { ok: true }
+  | { ok: false; code: typeof BOUND_SECRETS_NOT_CONSUMED; message: string };
+
+/**
+ * Hydrate `process.env` from both bind files and remove them from disk.
+ * Returns a failure when either secret is still readable afterwards.
+ *
+ * Both paths are platform constants, deliberately not the `CURSOR_API_KEY_FILE`
+ * override that {@link resolveApiKeySync} honors. That override is a read
+ * chain; this is a destructive consume. Following it here would let authored
+ * code redirect the destroy at a decoy path — reporting success while the real
+ * bind file stays live — and would delete an operator's own long-lived key
+ * file on a surface that points the variable at one.
+ */
+export function consumeHostedBoundSecrets(options?: {
+  apiKeyFilePath?: string;
+  deploymentSecretsFilePath?: string;
+}): HostedBoundSecretsResult {
+  const survivors: string[] = [];
+
+  const secretsPath =
+    options?.deploymentSecretsFilePath ??
+    DEFAULT_AGENT_SERVE_DEPLOYMENT_SECRETS_FILE;
+  const secrets = consumeBoundDeploymentSecrets(secretsPath);
+  if (secrets.disposal.state === "readable") {
+    survivors.push(`${secretsPath} (${secrets.disposal.reason})`);
+  }
+
+  const apiKeyPath = options?.apiKeyFilePath ?? DEFAULT_CURSOR_API_KEY_FILE;
+  const apiKey = consumeBoundCursorApiKey({ filePath: apiKeyPath });
+  if (apiKey.disposal.state === "readable") {
+    survivors.push(`${apiKeyPath} (${apiKey.disposal.reason})`);
+  }
+
+  if (survivors.length === 0) {
+    return { ok: true };
+  }
+  return {
+    ok: false,
+    code: BOUND_SECRETS_NOT_CONSUMED,
+    message:
+      `Task-bind secrets are still readable after being hydrated into the ` +
+      `environment, so authored work did not run: ${survivors.join(", ")}.`,
+  };
+}

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

@@ -4,11 +4,18 @@
  * 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.
+ * arrived, then destroys the document: `process.env` is the source authored
+ * code reads, and the file is only how the value crossed the process
+ * boundary.
  */
 
 import { readFileSync } from "node:fs";
 
+import {
+  type BoundSecretFileDisposal,
+  destroyBoundSecretFile,
+} from "./bound-secret-file.js";
+
 export const DEFAULT_AGENT_SERVE_DEPLOYMENT_SECRETS_FILE =
   "/run/cursor/secrets/AGENT_SERVE_DEPLOYMENT_SECRETS.json";
 
@@ -48,17 +55,11 @@ function parseBoundSecrets(path: string): Record<string, string> | undefined {
 }
 
 /**
- * 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.
+ * Apply the latest bound document to `process.env`. An empty valid document
+ * removes values loaded by an earlier bind after the deployment secret was
+ * unset, which is why the applied names are tracked across calls.
  */
-export function refreshBoundDeploymentSecrets(
-  path: string = DEFAULT_AGENT_SERVE_DEPLOYMENT_SECRETS_FILE
-): void {
-  const secrets = parseBoundSecrets(path);
-  if (secrets === undefined) {
-    return;
-  }
+function applyBoundSecrets(secrets: Record<string, string>): void {
   for (const name of appliedSecretNames) {
     if (!(name in secrets)) {
       delete process.env[name];
@@ -70,3 +71,33 @@ export function refreshBoundDeploymentSecrets(
     appliedSecretNames.add(name);
   }
 }
+
+export type BoundDeploymentSecretsConsumeResult = {
+  /** The document supplied values on this call. */
+  applied: boolean;
+  disposal: BoundSecretFileDisposal;
+};
+
+/**
+ * Apply the bound document to `process.env`, then destroy it.
+ *
+ * The env refresh always runs first, so a failed destroy never costs the
+ * request its secrets. A malformed document is destroyed too: it carries no
+ * values this process can use, and leaving it on disk only leaves whatever
+ * the control plane did manage to write.
+ *
+ * A `readable` disposal means the document survived; hosted callers must fail
+ * the request rather than run authored code next to a live secrets file.
+ */
+export function consumeBoundDeploymentSecrets(
+  path: string = DEFAULT_AGENT_SERVE_DEPLOYMENT_SECRETS_FILE
+): BoundDeploymentSecretsConsumeResult {
+  const secrets = parseBoundSecrets(path);
+  if (secrets !== undefined) {
+    applyBoundSecrets(secrets);
+  }
+  return {
+    applied: secrets !== undefined,
+    disposal: destroyBoundSecretFile(path),
+  };
+}

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

@@ -1,7 +1,7 @@
 /**
  * Task-time bind paths for hosted deployment file-store source ids.
  *
- * Freeze v2 snapshots start `agent-serve serve` at bake time without a service
+ * Freeze v2 snapshots start `agent-sdk serve` at bake time without a service
  * account, so neither store id is in process env. Execute-from-freeze binds
  * the deployment credential and store ids into `/run/cursor/secrets/` without
  * restarting July — the same pattern as {@link DEFAULT_CURSOR_API_KEY_FILE}.
@@ -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-account-mcp-auth.ts

@@ -20,6 +20,7 @@ import type {
 } from "./cursor/backend-client.js";
 import { LOG_PREFIX } from "./distribution.js";
 import { openBrowser } from "./mcp-oauth.js";
+import { sleep as defaultSleep } from "./sleep.js";
 
 const DEFAULT_POLL_INTERVAL_MS = 3_000;
 const DEFAULT_POLL_TIMEOUT_MS = 5 * 60 * 1000;
@@ -66,10 +67,6 @@ export interface AuthorizeCursorAccountConnectorsResult {
   errored: Array<{ name: string; error: string }>;
 }
 
-function sleepMs(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
 /**
  * Authorize the deployment service account for the connection's connectors.
  * Already-authorized connectors are skipped; the rest get a browser OAuth
@@ -81,7 +78,7 @@ export async function authorizeCursorAccountConnectors(
   const { backendClient, teamId, serviceAccountId, connectionName, out, err } =
     args;
   const open = args.openBrowserImpl ?? openBrowser;
-  const sleep = args.sleep ?? sleepMs;
+  const sleep = args.sleep ?? defaultSleep;
   const pollIntervalMs = args.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
   const pollTimeoutMs = args.pollTimeoutMs ?? DEFAULT_POLL_TIMEOUT_MS;
   const redirectUri = mcpOauthRedirectUri();

package/src/internal/cursor-deployment-relay.ts

@@ -60,14 +60,18 @@ export function currentDeploymentSubscriptions(
   return typeof subscriptions === "function" ? subscriptions() : subscriptions;
 }
 
-/** Normalize the channel's `deploySourceUris` option into concrete subscriptions. */
+/**
+ * Normalize the channel's `deploySourceUris` option into concrete
+ * subscriptions. An omitted or empty option resolves to none, which callers
+ * read as "defer to the deploy scope".
+ */
 export function resolveDeploymentSubscriptions(options: {
-  deploySourceUris: readonly (string | DeploymentSubscription)[];
+  deploySourceUris?: readonly (string | DeploymentSubscription)[];
   environments?: readonly string[];
   events?: readonly DeploymentEventType[];
 }): ResolvedSubscription[] {
   const bySource = new Map<string, ResolvedSubscription>();
-  for (const entry of options.deploySourceUris) {
+  for (const entry of options.deploySourceUris ?? []) {
     const subscription: DeploymentSubscription =
       typeof entry === "string" ? { deploySourceUri: entry } : entry;
     // Case-folded only: `Deployment.deploy_source_uri` has no documented
@@ -106,10 +110,10 @@ export function resolveDeploymentSubscriptions(options: {
         ? []
         : [...new Set([...existing.environments, ...environments])];
   }
-  // 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.
+  // Empty means "this channel names nothing". The relay wire reads that as
+  // deregistration, hosted admission reads it as "defer to the deploy
+  // scope". The host re-resolves on each heartbeat, so a channel that later
+  // fills `deploySourceUris` registers without a restart.
   return [...bySource.values()];
 }