@cursor/july 0.1.114 → 0.2.1

package/src/internal/artifacts-store.ts

@@ -31,14 +31,34 @@ import type {
   ArtifactTagInput,
   JsonValue,
 } from "../types.js";
+import { mapBounded } from "./bounded.js";
+
+/**
+ * Row-body hydration fan-out cap. `list()` fetches one object per row; on
+ * the Agent Store each fetch is a control-plane request, and an unbounded
+ * `Promise.all` over ~1k rows is a fleet-visible read burst (the 2026-09-18
+ * Agent Store read storm was this exact fan-out, run once per insert by the
+ * pre-metadata eviction path).
+ */
+const ROW_HYDRATION_CONCURRENCY = 8;
+
+/** One row's identity + modification metadata, without its body. */
+interface ArtifactRowMeta {
+  id: string;
+  /** Last-modified epoch ms, when the backing store tracks one. */
+  mtimeMs?: number;
+}
 
 interface ArtifactRowStore {
   get(id: string): Promise<ArtifactRecord | undefined>;
   put(record: ArtifactRecord): Promise<void>;
   delete(id: string): Promise<void>;
   list(): Promise<ArtifactRecord[]>;
-  /** Row count without hydrating bodies — the per-insert cap check. */
-  count(): Promise<number>;
+  /**
+   * Row ids + modification metadata without hydrating bodies — the
+   * per-insert cap check and (when mtimes are tracked) the eviction order.
+   */
+  listMeta(): Promise<ArtifactRowMeta[]>;
 }
 
 /** File/blob payload bytes, keyed by artifact id (metadata lives on the row). */
@@ -202,21 +222,54 @@ export class ArtifactsStore {
     return { kind, data: input.data };
   }
 
+  /**
+   * Trim to the retention cap from listing metadata alone. Past the cap
+   * this runs on every new-row insert, so it must not hydrate row bodies:
+   * on the Agent Store that is one read per row (~`max` reads per insert,
+   * forever, since eviction trims right back to the cap) — the 2026-09-18
+   * read storm on the security-reviewer deployment. The store listing
+   * carries last-modified metadata, and a row is rewritten on every upsert,
+   * so listing mtime orders rows the same way their `updatedAt` does.
+   */
   private async evictPastCap(): Promise<void> {
-    if ((await this.rows.count()) <= this.max) {
+    const metas = await this.rows.listMeta();
+    const excess = metas.length - this.max;
+    if (excess <= 0) {
       return;
     }
-    const records = await this.rows.list();
-    if (records.length <= this.max) {
-      return;
+    for (const id of await this.oldestRowIds(metas, excess)) {
+      await this.rows.delete(id);
+      // Without the row body there is no `content` flag to consult; delete
+      // the payload unconditionally — absent payloads delete as a no-op.
+      await this.content.delete(id);
     }
-    const oldestFirst = records.sort((a, b) => byNewestUpdated(b, a));
-    for (const record of oldestFirst.slice(0, records.length - this.max)) {
-      await this.rows.delete(record.id);
-      if (record.content !== undefined) {
-        await this.content.delete(record.id);
-      }
+  }
+
+  /** The `excess` oldest row ids, cheapest available ordering first. */
+  private async oldestRowIds(
+    metas: ArtifactRowMeta[],
+    excess: number
+  ): Promise<string[]> {
+    if (metas.some(meta => meta.mtimeMs !== undefined)) {
+      // A store that tracks mtimes must never regress to per-insert
+      // hydration. The rare entry missing one (anomalous on such a store)
+      // sorts oldest via the comparator's `?? 0` and gets evicted first —
+      // evicting an anomaly beats re-reading every row on every insert.
+      return metas
+        .sort(byOldestModified)
+        .slice(0, excess)
+        .map(meta => meta.id);
     }
+    // A store that tracks no modification times at all (the local
+    // filesystem store, deliberately) leaves only the rows' own
+    // `updatedAt`: hydrate — bounded — and order exactly. Corrupt rows
+    // drop out of `list()`, so recompute the excess against the rows that
+    // actually parsed.
+    const records = await this.rows.list();
+    return records
+      .sort((a, b) => byNewestUpdated(b, a))
+      .slice(0, Math.max(0, records.length - this.max))
+      .map(record => record.id);
   }
 }
 
@@ -228,6 +281,18 @@ export function artifactIdForKey(key: string): string {
   return `art_${createHash("sha256").update(key, "utf8").digest("hex").slice(0, 32)}`;
 }
 
+/**
+ * Oldest-modified first. Store mtimes can be coarse (S3 rounds to the
+ * second), so equal stamps tie-break by id — deterministic, and within a
+ * same-stamp cohort any victim is equally past the retention cap.
+ */
+function byOldestModified(a: ArtifactRowMeta, b: ArtifactRowMeta): number {
+  if (a.mtimeMs !== b.mtimeMs) {
+    return (a.mtimeMs ?? 0) - (b.mtimeMs ?? 0);
+  }
+  return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+}
+
 function byNewestUpdated(a: ArtifactRecord, b: ArtifactRecord): number {
   if (a.updatedAt !== b.updatedAt) {
     return a.updatedAt < b.updatedAt ? 1 : -1;
@@ -311,8 +376,10 @@ function createSinkRowStore(
       const entries = await sink.list(
         agentStoreKeys.artifactRowPrefix(agentName)
       );
-      const bodies = await Promise.all(
-        entries.map(entry => sink.get(entry.key))
+      const bodies = await mapBounded(
+        entries,
+        ROW_HYDRATION_CONCURRENCY,
+        entry => sink.get(entry.key)
       );
       const records: ArtifactRecord[] = [];
       for (const body of bodies) {
@@ -323,15 +390,42 @@ function createSinkRowStore(
       }
       return records;
     },
-    async count(): Promise<number> {
-      const entries = await sink.list(
-        agentStoreKeys.artifactRowPrefix(agentName)
-      );
-      return entries.length;
+    async listMeta(): Promise<ArtifactRowMeta[]> {
+      const prefix = agentStoreKeys.artifactRowPrefix(agentName);
+      const metas: ArtifactRowMeta[] = [];
+      for (const entry of await sink.list(prefix)) {
+        const id = rowIdFromName(entry.key.slice(prefix.length));
+        if (id !== undefined) {
+          metas.push({ id, mtimeMs: entry.mtimeMs });
+        }
+      }
+      return metas;
     },
   };
 }
 
+/**
+ * Invert the row naming scheme (`encodeURIComponent(id) + ".json"`).
+ * Foreign keys under the prefix — no `.json` suffix, malformed escapes,
+ * non-canonical encodings — read as absent rather than throwing. The
+ * round-trip check matters for eviction: a name that decodes but does not
+ * re-encode to itself (`a+b.json`, `foo bar.json`) would count toward the
+ * cap yet be undeletable through `key(id)`, leaving a phantom victim that
+ * every subsequent insert re-selects and fails to remove.
+ */
+function rowIdFromName(name: string): string | undefined {
+  if (!name.endsWith(".json") || name.includes("/")) {
+    return undefined;
+  }
+  const encoded = name.slice(0, -".json".length);
+  try {
+    const id = decodeURIComponent(encoded);
+    return encodeURIComponent(id) === encoded ? id : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 function createSinkContentStore(
   sink: FileSink,
   agentName: string
@@ -410,18 +504,30 @@ function createFilesystemRowStore(stateRoot: string): ArtifactRowStore {
       }
       return records;
     },
-    async count(): Promise<number> {
+    async listMeta(): Promise<ArtifactRowMeta[]> {
+      // No mtimes on purpose: local rows are cheap to hydrate, and the
+      // rows' own `updatedAt` orders eviction exactly, immune to coarse
+      // filesystem timestamp granularity.
+      let names: string[];
       try {
-        const names = await readdir(dir);
-        return names.filter(
-          name => !name.startsWith(".") && name.endsWith(".json")
-        ).length;
+        names = await readdir(dir);
       } catch (error) {
         if ((error as NodeJS.ErrnoException).code === "ENOENT") {
-          return 0;
+          return [];
         }
         throw error;
       }
+      const metas: ArtifactRowMeta[] = [];
+      for (const name of names) {
+        if (name.startsWith(".")) {
+          continue;
+        }
+        const id = rowIdFromName(name);
+        if (id !== undefined) {
+          metas.push({ id });
+        }
+      }
+      return metas;
     },
   };
 }

package/src/internal/cli-deploy.ts

@@ -1658,11 +1658,18 @@ export async function cmdStop(
   }
   const cancellation =
     "cancellation" in accepted ? accepted.cancellation : undefined;
+  // The backend escalates a publisher's stop of a multi-tenant app to the
+  // application-level suspension; say so, and how to undo it.
+  const stoppedGlobally = "scope" in accepted && accepted.scope === "global";
   if (ctx.noWait) {
     if (ctx.json) {
       ctx.out(`${JSON.stringify(accepted, null, 2)}\n`);
     } else {
-      ctx.out(`Stop accepted for ${slug} (status: ${accepted.status}).\n`);
+      ctx.out(
+        stoppedGlobally
+          ? `Stop accepted for ${slug} across all tenants (status: ${accepted.status}).\n`
+          : `Stop accepted for ${slug} (status: ${accepted.status}).\n`
+      );
     }
     return cancellation?.failed === 0 || cancellation === undefined ? 0 : 1;
   }
@@ -1681,6 +1688,10 @@ export async function cmdStop(
   }
   if (ctx.json) {
     ctx.out(`${JSON.stringify(detail, null, 2)}\n`);
+  } else if (stoppedGlobally) {
+    ctx.out(
+      `Stopped ${slug} across all tenants (team ${ctx.teamId}); resume with \`${CLI} start ${slug} --global\`.\n`
+    );
   } else {
     ctx.out(`Stopped ${slug} (team ${ctx.teamId}).\n`);
   }

package/src/internal/cursor/cursor-api-transport.ts

@@ -0,0 +1,73 @@
+/**
+ * The one resolution of "which Cursor control plane, as whom" for hosted
+ * transports. The verb-lane files sink (`files-backends/cursor-hosted.ts`)
+ * and the domain-lane store API client (`store-api-client.ts`) both build on
+ * these, so the pod credential and base URL resolve identically on every
+ * wire — one place to change, no drift between lanes.
+ */
+
+/**
+ * Same default as the hosted storage backend, inlined so these entrypoints
+ * do not import CLI code.
+ */
+export const DEFAULT_CURSOR_EXTERNAL_API_URL = "https://api.cursor.com";
+
+export interface CursorApiTransportOptions {
+  /** Control-plane base URL (default: `CURSOR_API_BASE_URL`, else api.cursor.com). */
+  baseUrl?: string;
+  /** Bearer credential (default: `CURSOR_API_KEY`). */
+  apiKey?: string;
+  /**
+   * Lazy credential, re-resolved on every call and preferred over
+   * {@link apiKey} — hosted freeze snapshots listen unsigned and bind the
+   * key file after serve start. Kept separate so `apiKey` stays a plain
+   * string.
+   */
+  resolveApiKey?: () => string | undefined;
+  /** Test seam; defaults to global fetch. */
+  fetch?: typeof fetch;
+}
+
+function trimTrailingSlash(raw: string): string {
+  const trimmed = raw.trim();
+  return trimmed.endsWith("/") ? trimmed.slice(0, -1) : trimmed;
+}
+
+export function resolveCursorApiBaseUrl(
+  options: CursorApiTransportOptions
+): string {
+  return trimTrailingSlash(
+    options.baseUrl ??
+      process.env.CURSOR_API_BASE_URL ??
+      DEFAULT_CURSOR_EXTERNAL_API_URL
+  );
+}
+
+/**
+ * The pod credential is the whole authorization on every hosted wire: the
+ * API resolves the caller's deployment from it, so there is no second,
+ * narrower credential to manage. Fails loudly rather than defaulting —
+ * calling the control plane as nobody is worse than not calling.
+ */
+export function resolveCursorApiKey(
+  options: CursorApiTransportOptions
+): string {
+  const configured = options.resolveApiKey?.() ?? options.apiKey;
+  const key = (configured ?? process.env.CURSOR_API_KEY)?.trim();
+  if (key === undefined || key === "") {
+    throw new Error(
+      "Cursor hosted transport requires CURSOR_API_KEY (deployment pod credential on Cursor hosting)"
+    );
+  }
+  return key;
+}
+
+export function resolveCursorApiFetch(
+  options: CursorApiTransportOptions
+): typeof fetch {
+  const impl = options.fetch ?? globalThis.fetch;
+  if (typeof impl !== "function") {
+    throw new Error("Cursor hosted transport requires fetch");
+  }
+  return impl;
+}

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

@@ -26,6 +26,41 @@ export const DEFAULT_AGENT_SERVE_STORE_PROTOCOL_FILE =
  */
 export const AGENT_SERVE_FACTORY_FLUSH_PROTOCOL = "factory-flush-v1";
 
+/**
+ * Pin value additionally enabling the domain-call lane
+ * (`POST /internal/agentsdk/store/api/<call>`), where the server owns the
+ * storage pattern for framework state — starting with `memory.append`. A
+ * strict superset of {@link AGENT_SERVE_FACTORY_FLUSH_PROTOCOL}: verbs keep
+ * riding the factory flush wire under this pin too. The same fail-safe
+ * applies in both directions — an unknown value keeps today's behavior, and
+ * re-pinning to `factory-flush-v1` turns the domain lane back off without a
+ * client change.
+ */
+export const AGENT_SERVE_FACTORY_API_PROTOCOL = "factory-api-v1";
+
+/**
+ * Does this pin select the factory flush wire for the store verbs? True for
+ * the flush pin and for the domain-API superset pin.
+ */
+export function storeProtocolEnablesFactoryFlush(
+  protocol: string | undefined
+): boolean {
+  return (
+    protocol === AGENT_SERVE_FACTORY_FLUSH_PROTOCOL ||
+    protocol === AGENT_SERVE_FACTORY_API_PROTOCOL
+  );
+}
+
+/**
+ * Does this pin enable the domain-call lane (server-owned storage patterns)?
+ * Only its exact value does; everything else keeps the client-side patterns.
+ */
+export function storeProtocolEnablesStoreApi(
+  protocol: string | undefined
+): boolean {
+  return protocol === AGENT_SERVE_FACTORY_API_PROTOCOL;
+}
+
 const STORE_SOURCE_ID_ENV = "AGENT_SERVE_STORE_SOURCE_ID";
 const FRAMEWORK_STORE_SOURCE_ID_ENV = "AGENT_SERVE_FRAMEWORK_STORE_SOURCE_ID";
 const STORE_SOURCE_ID_FILE_ENV = "AGENT_SERVE_STORE_SOURCE_ID_FILE";