@cursor/july 0.2.0 → 0.2.1

package/src/files-backends/cursor-hosted.ts

@@ -57,19 +57,19 @@ import {
   type FileSinkPutResult,
 } from "../files.js";
 import {
-  AGENT_SERVE_FACTORY_FLUSH_PROTOCOL,
+  type CursorApiTransportOptions,
+  resolveCursorApiBaseUrl,
+  resolveCursorApiFetch,
+  resolveCursorApiKey,
+} from "../internal/cursor/cursor-api-transport.js";
+import {
   resolveDeploymentStoreSourceIdSync,
   resolveFrameworkStoreSourceIdSync,
   resolveStoreProtocolSync,
+  storeProtocolEnablesFactoryFlush,
 } from "../internal/cursor/hosted-store-secrets.js";
 import { createAgentStorePresignedUrlValidatorForBackend } from "./agent-store-presigned-url.js";
 
-/**
- * Same default as the hosted storage backend, inlined so this entrypoint does
- * not import CLI code.
- */
-const DEFAULT_CURSOR_EXTERNAL_API_URL = "https://api.cursor.com";
-
 const AGENT_SERVE_FILES_PATH = "/v0/agent-serve-files";
 
 /**
@@ -156,18 +156,12 @@ export function isCursorUserStoreFilesAvailable(
   return key !== undefined && key !== "";
 }
 
-export interface CursorHostedFilesOptions {
-  /** 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;
+/**
+ * Base URL / credential / fetch resolution is the shared
+ * {@link CursorApiTransportOptions} (`internal/cursor/cursor-api-transport.ts`),
+ * so this sink and the domain-lane store API client resolve identically.
+ */
+export interface CursorHostedFilesOptions extends CursorApiTransportOptions {
   /** File store to address (default: `AGENT_SERVE_STORE_SOURCE_ID`). */
   storeSourceId?: string;
   /**
@@ -178,13 +172,12 @@ export interface CursorHostedFilesOptions {
   resolveStoreSourceId?: () => string | undefined;
   /**
    * Lazy store protocol pin (default: env, then the task-bound file). When it
-   * answers {@link AGENT_SERVE_FACTORY_FLUSH_PROTOCOL} and the source id maps
-   * to a deployment store role, requests ride the factory store API instead
-   * of `/v0/agent-serve-files`. Any other value keeps `/v0`.
+   * enables the factory flush wire (`factory-flush-v1`, or the superset
+   * domain-API pin `factory-api-v1`) and the source id maps to a deployment
+   * store role, requests ride the factory store API instead of
+   * `/v0/agent-serve-files`. Any other value keeps `/v0`.
    */
   resolveStoreProtocol?: () => string | undefined;
-  /** Test seam; defaults to global fetch. */
-  fetch?: typeof fetch;
 }
 
 /**
@@ -295,7 +288,7 @@ export function cursorHostedFiles(
     const sourceId = resolveStoreSourceId(options);
     const protocol =
       options.resolveStoreProtocol?.() ?? resolveStoreProtocolSync();
-    if (protocol === AGENT_SERVE_FACTORY_FLUSH_PROTOCOL) {
+    if (storeProtocolEnablesFactoryFlush(protocol)) {
       // The factory API addresses stores by role, so map the pinned source id
       // back to the role it was pinned from. A source id matching neither (a
       // local-dev override) has no role there and stays on `/v0`, as does any
@@ -567,7 +560,7 @@ export function cursorHostedFiles(
           };
         }
         try {
-          const response = await fetchImpl(options)(
+          const response = await resolveCursorApiFetch(options)(
             assertPresignedUrlSafe(options, instruction.url),
             {
               method: "PUT",
@@ -818,7 +811,7 @@ export function cursorHostedFiles(
         if (url === undefined) {
           return undefined;
         }
-        const response = await fetchImpl(options)(
+        const response = await resolveCursorApiFetch(options)(
           assertPresignedUrlSafe(options, url),
           {
             method: "GET",
@@ -992,9 +985,9 @@ function assertPresignedUrlSafe(
     return url.toString();
   }
   try {
-    createAgentStorePresignedUrlValidatorForBackend(resolveBaseUrl(options))(
-      url
-    );
+    createAgentStorePresignedUrlValidatorForBackend(
+      resolveCursorApiBaseUrl(options)
+    )(url);
   } catch (error) {
     throw new Error(
       `cursorHostedFiles: refused presigned URL: ${
@@ -1005,14 +998,6 @@ function assertPresignedUrlSafe(
   return url.toString();
 }
 
-function fetchImpl(options: CursorHostedFilesOptions): typeof fetch {
-  const impl = options.fetch ?? globalThis.fetch;
-  if (typeof impl !== "function") {
-    throw new Error("cursorHostedFiles requires fetch");
-  }
-  return impl;
-}
-
 /**
  * The file store this engine's deployment owns. Every request names it, so
  * the server resolves the store row and this process never handles a store id.
@@ -1034,17 +1019,6 @@ function resolveStoreSourceId(options: CursorHostedFilesOptions): string {
   return id;
 }
 
-function resolveApiKey(options: CursorHostedFilesOptions): string {
-  const configured = options.resolveApiKey?.() ?? options.apiKey;
-  const key = (configured ?? process.env.CURSOR_API_KEY)?.trim();
-  if (key === undefined || key === "") {
-    throw new Error(
-      "cursorHostedFiles requires CURSOR_API_KEY (deployment pod credential on Cursor hosting)"
-    );
-  }
-  return key;
-}
-
 const DEV_PRESIGN_HOSTS: ReadonlySet<string> = new Set(
   (process.env.CURSOR_HOSTED_FILES_DEV_PRESIGN_HOSTS ?? "")
     .split(",")
@@ -1052,19 +1026,6 @@ const DEV_PRESIGN_HOSTS: ReadonlySet<string> = new Set(
     .filter(host => host.length > 0)
 );
 
-function resolveBaseUrl(options: CursorHostedFilesOptions): string {
-  return trimTrailingSlash(
-    options.baseUrl ??
-      process.env.CURSOR_API_BASE_URL ??
-      DEFAULT_CURSOR_EXTERNAL_API_URL
-  );
-}
-
-function trimTrailingSlash(raw: string): string {
-  const trimmed = raw.trim();
-  return trimmed.endsWith("/") ? trimmed.slice(0, -1) : trimmed;
-}
-
 /**
  * Public agent-serve-files API call. The pod credential is the whole authorization:
  * the API forwards this caller's identity to the store service, which checks it
@@ -1077,7 +1038,7 @@ async function storePost<T>(
 ): Promise<T> {
   return await postJson<T>(
     options,
-    `${resolveBaseUrl(options)}${AGENT_SERVE_FILES_PATH}${path}`,
+    `${resolveCursorApiBaseUrl(options)}${AGENT_SERVE_FILES_PATH}${path}`,
     body
   );
 }
@@ -1088,7 +1049,7 @@ async function storeGet<T>(
 ): Promise<T> {
   return await sendJson<T>(
     options,
-    `${resolveBaseUrl(options)}${AGENT_SERVE_FILES_PATH}${path}`,
+    `${resolveCursorApiBaseUrl(options)}${AGENT_SERVE_FILES_PATH}${path}`,
     "GET"
   );
 }
@@ -1096,7 +1057,9 @@ async function storeGet<T>(
 /**
  * Factory store API call — same base URL and pod credential as
  * {@link storePost}, different path family. The server resolves the
- * deployment (and the addressed store role) from the credential.
+ * deployment (and the addressed store role) from the credential. The
+ * domain-call lane one path family deeper is NOT here: it belongs to the
+ * store API client (`../internal/cursor/store-api-client.ts`).
  */
 async function flushPost<T>(
   options: CursorHostedFilesOptions,
@@ -1105,7 +1068,7 @@ async function flushPost<T>(
 ): Promise<T> {
   return await postJson<T>(
     options,
-    `${resolveBaseUrl(options)}${AGENTSDK_STORE_PATH}${path}`,
+    `${resolveCursorApiBaseUrl(options)}${AGENTSDK_STORE_PATH}${path}`,
     body
   );
 }
@@ -1124,10 +1087,10 @@ async function sendJson<T>(
   method: "GET" | "POST",
   body?: Record<string, unknown>
 ): Promise<T> {
-  const response = await fetchImpl(options)(url, {
+  const response = await resolveCursorApiFetch(options)(url, {
     method,
     headers: {
-      Authorization: `Bearer ${resolveApiKey(options)}`,
+      Authorization: `Bearer ${resolveCursorApiKey(options)}`,
       ...(body === undefined ? {} : { "Content-Type": "application/json" }),
     },
     ...(body === undefined ? {} : { body: JSON.stringify(body) }),

package/src/index.ts

@@ -166,6 +166,7 @@ export type {
   ReminderDefinition,
   ReminderFireContext,
   ReminderFireResult,
+  ReminderFollowupOptions,
   ReminderHandlerConfig,
   ReminderHostApi,
   ReminderInfo,

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/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";