@cursor/july 0.1.109 → 0.1.112

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

@@ -7,12 +7,17 @@
  * URLs. File contents never transit the control plane, so a large artifact
  * costs S3 bandwidth rather than backend memory.
  *
- * Everything goes through the public API under `/v0/agent-serve-files`, the same
- * surface any API-key holder gets. This process is an ordinary client of it —
- * there is no private endpoint, no second base URL, and nothing here that only
- * works because the caller happens to be an Agent Serve engine. That matters
- * beyond tidiness: a self-hosted deployment, a CI job, or a customer script can
- * drive the same store with the same requests.
+ * By default everything goes through the public API under
+ * `/v0/agent-serve-files`, the same surface any API-key holder gets — a
+ * self-hosted deployment, a CI job, or a customer script can drive the same
+ * store with the same requests. Cursor-managed v2 pods can instead be pinned
+ * (per deployment, at task-time bind) onto the engine-facing factory store API
+ * under `/internal/agentsdk/store`: same host, same credential, same stores
+ * and S3 objects, but flush-shaped — one control-plane request settles a whole
+ * `putMany` batch or a conditional delete, where `/v0` costs a presign POST
+ * plus stat GETs and a delete POST. The pin fails safe: an absent or
+ * unrecognized protocol value, or a source id that maps to neither deployment
+ * store role, keeps `/v0`.
  *
  * Two things follow. There is no Agent Store token: a token narrows an identity
  * to one store and one capability, which is what a caller that cannot hold a
@@ -51,7 +56,12 @@ import {
   type FileSinkEntry,
   type FileSinkPutResult,
 } from "../files.js";
-import { resolveDeploymentStoreSourceIdSync } from "../internal/cursor/hosted-store-secrets.js";
+import {
+  AGENT_SERVE_FACTORY_FLUSH_PROTOCOL,
+  resolveDeploymentStoreSourceIdSync,
+  resolveFrameworkStoreSourceIdSync,
+  resolveStoreProtocolSync,
+} from "../internal/cursor/hosted-store-secrets.js";
 import { createAgentStorePresignedUrlValidatorForBackend } from "./agent-store-presigned-url.js";
 
 /**
@@ -62,6 +72,16 @@ const DEFAULT_CURSOR_EXTERNAL_API_URL = "https://api.cursor.com";
 
 const AGENT_SERVE_FILES_PATH = "/v0/agent-serve-files";
 
+/**
+ * Engine-facing store API on the factory service — same host, different path
+ * family. Selected per pod by the task-bound protocol pin
+ * ({@link resolveStoreProtocolSync}); the server resolves the deployment and
+ * its stores from the pod credential, so requests carry a store *role*
+ * (`deployment` | `framework`), never a store id. One flush request replaces
+ * the presign POST plus the stat GETs and delete POST a turn costs on `/v0`.
+ */
+const AGENTSDK_STORE_PATH = "/internal/agentsdk/store";
+
 /**
  * Pinned by the deploy pipeline for every Cursor-managed deployment — which
  * provisions the file store it names in the same step — and reserved from
@@ -156,14 +176,25 @@ export interface CursorHostedFilesOptions {
    * after serve start without restarting July.
    */
   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`.
+   */
+  resolveStoreProtocol?: () => string | undefined;
   /** Test seam; defaults to global fetch. */
   fetch?: typeof fetch;
 }
 
-/** What a file operation needs: where this deployment's files live. */
-interface FilesTarget {
-  path(suffix?: string): string;
-}
+/**
+ * What a file operation needs: where this deployment's files live, and which
+ * wire reaches them. `v0` addresses the public API by store source id; `flush`
+ * addresses the factory store API by role and lets the server resolve.
+ */
+type FilesTarget =
+  | { wire: "v0"; path(suffix?: string): string }
+  | { wire: "flush"; store: "deployment" | "framework" };
 
 /**
  * Wire shapes from `/v0/agent-serve-files`. Declared loosely on purpose: this is a
@@ -197,6 +228,25 @@ interface ApiDeleteResponse {
   files?: Array<{ path?: string; status?: string; etag?: string }>;
 }
 
+/**
+ * Per-op outcome from the factory store API's `flush` route, index-aligned
+ * with the request ops. A put answers `url`/`headers`; a delete answers
+ * `status`; declared loosely for the same additive-change reason as the
+ * `/v0` shapes above.
+ */
+interface FlushWireOpOutcome {
+  path?: string;
+  url?: string;
+  headers?: Record<string, string>;
+  error?: string;
+  status?: string;
+  etag?: string;
+}
+
+interface FlushWireResponse {
+  ops?: FlushWireOpOutcome[];
+}
+
 type HostedFilesMethods = Omit<FileSink, "get"> & {
   /** Narrower than {@link FileSink.get}: this backend always reports the etag. */
   get(key: string): Promise<FileSinkBody | undefined>;
@@ -232,16 +282,33 @@ export function cursorHostedFiles(
   /**
    * Run `call` against this deployment's files.
    *
-   * No network call and nothing cached: the store source id comes from the
-   * environment and the server maps it to a store on every request. Resolved
-   * per call rather than once at construction so a misconfigured environment
-   * fails where the operation is, not where the sink was created.
+   * No network call and nothing cached: the store source id and protocol pin
+   * come from the environment (or task-bound files) and the server maps them
+   * on every request. Resolved per call rather than once at construction so a
+   * misconfigured environment fails where the operation is, not where the
+   * sink was created — and so a protocol pin bound after serve start takes
+   * effect without a restart.
    */
   async function withFiles<T>(
     call: (files: FilesTarget) => Promise<T>
   ): Promise<T> {
     const sourceId = resolveStoreSourceId(options);
+    const protocol =
+      options.resolveStoreProtocol?.() ?? resolveStoreProtocolSync();
+    if (protocol === AGENT_SERVE_FACTORY_FLUSH_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
+      // protocol value this runtime does not recognize.
+      if (sourceId === resolveFrameworkStoreSourceIdSync()) {
+        return await call({ wire: "flush", store: "framework" });
+      }
+      if (sourceId === resolveDeploymentStoreSourceIdSync()) {
+        return await call({ wire: "flush", store: "deployment" });
+      }
+    }
     return await call({
+      wire: "v0",
       path: (suffix = "") => `/${encodeURIComponent(sourceId)}${suffix}`,
     });
   }
@@ -252,6 +319,14 @@ export function cursorHostedFiles(
     directory: string,
     pageToken: string | undefined
   ): Promise<ApiFileListing> {
+    if (files.wire === "flush") {
+      return await flushPost<ApiFileListing>(options, "/list", {
+        store: files.store,
+        path: directory,
+        limit: DIRECTORY_PAGE_SIZE,
+        ...(pageToken === undefined ? {} : { pageToken }),
+      });
+    }
     const query = new URLSearchParams({
       path: directory,
       limit: String(DIRECTORY_PAGE_SIZE),
@@ -265,9 +340,19 @@ export function cursorHostedFiles(
     );
   }
 
+  /** The unscoped whole-store listing, on whichever wire the target rides. */
+  async function unscopedListing(files: FilesTarget): Promise<ApiFileListing> {
+    if (files.wire === "flush") {
+      return await flushPost<ApiFileListing>(options, "/list", {
+        store: files.store,
+      });
+    }
+    return await storeGet<ApiFileListing>(options, files.path());
+  }
+
   async function listEntries(prefix: string): Promise<FileSinkEntry[]> {
-    return await withFiles(async (files) => {
-      const raw = await storeGet<ApiFileListing>(options, files.path());
+    return await withFiles(async files => {
+      const raw = await unscopedListing(files);
       if (raw.complete === true) {
         const out: FileSinkEntry[] = [];
         for (const file of raw.files ?? []) {
@@ -378,7 +463,7 @@ export function cursorHostedFiles(
   async function statKey(key: string): Promise<FileSinkEntry | undefined> {
     const slash = key.lastIndexOf("/");
     const directory = slash === -1 ? "" : key.slice(0, slash);
-    return await withFiles(async (files) => {
+    return await withFiles(async files => {
       let pageToken: string | undefined;
       for (let page = 0; page < MAX_DIRECTORY_PAGES; page += 1) {
         const raw = await directoryPage(files, directory, pageToken);
@@ -397,22 +482,224 @@ export function cursorHostedFiles(
     });
   }
 
+  /** One key's share of a (possibly multi-file) upload attempt. */
+  type UploadSpec = {
+    key: string;
+    body: Uint8Array;
+    precondition: { etag: string } | { new: true };
+  };
+  type UploadOutcome =
+    | { status: "ok"; result: FileSinkPutResult }
+    | { status: "conflict" }
+    | { status: "error"; error: unknown };
+
+  /**
+   * The shared presign for one upload attempt: a `/v0` upload POST, or one
+   * flush request whose put outcomes are reshaped into the same instruction
+   * list (an outcome without a `url` — an oversize refusal — surfaces exactly
+   * like a `/v0` multipart answer: no single-part instruction for that key).
+   */
+  async function presignUploads(
+    files: FilesTarget,
+    specs: UploadSpec[]
+  ): Promise<ApiPresignResponse> {
+    if (files.wire === "flush") {
+      const response = await flushPost<FlushWireResponse>(options, "/flush", {
+        store: files.store,
+        ops: specs.map(spec => ({
+          op: "put",
+          path: spec.key,
+          sha: createHash("sha256").update(spec.body).digest("hex"),
+          size: spec.body.byteLength,
+          ...spec.precondition,
+        })),
+      });
+      // Index-aligned with the request ops, entries without a `url` included:
+      // a refused op (oversize) must keep its slot so the by-path/positional
+      // instruction matching below cannot hand its sibling's presign to it,
+      // and the missing url surfaces as that key's own error.
+      return {
+        files: (response.ops ?? []).map(op => ({
+          path: op.path,
+          ...(typeof op.url === "string" && op.url !== ""
+            ? { url: op.url }
+            : {}),
+          headers: op.headers,
+        })),
+      };
+    }
+    return await storePost<ApiPresignResponse>(options, files.path("/upload"), {
+      files: specs.map(spec => ({
+        path: spec.key,
+        sha: createHash("sha256").update(spec.body).digest("hex"),
+        size: spec.body.byteLength,
+        ...spec.precondition,
+      })),
+    });
+  }
+
+  /**
+   * One presign call covering every spec, then parallel presigned PUTs.
+   * Outcomes are per spec: a 412 ("conflict") or a failed PUT for one key
+   * never disturbs its batch siblings. Only the presign itself is shared —
+   * a presign error throws and fails the whole attempt.
+   */
+  async function attemptUploads(
+    files: FilesTarget,
+    specs: UploadSpec[]
+  ): Promise<UploadOutcome[]> {
+    const presigned = await presignUploads(files, specs);
+    return await Promise.all(
+      specs.map(async (spec, index): Promise<UploadOutcome> => {
+        // Match by path, falling back to position for servers that answer
+        // in request order without echoing the path.
+        const instruction =
+          presigned.files?.find(file => file.path === spec.key) ??
+          presigned.files?.[index];
+        if (instruction?.url === undefined) {
+          // Files past the single-part threshold come back with a multipart
+          // plan instead of a url; this backend does not implement multipart.
+          return {
+            status: "error",
+            error: new Error(
+              `cursorHostedFiles: no single-part upload url for "${spec.key}" (too large?)`
+            ),
+          };
+        }
+        try {
+          const response = await fetchImpl(options)(
+            assertPresignedUrlSafe(options, instruction.url),
+            {
+              method: "PUT",
+              headers: instruction.headers ?? {},
+              // A view over bytes is a valid fetch body; the DOM lib types
+              // are narrower than the runtime, and copying into a Blob would
+              // double the memory for every upload.
+              body: spec.body as unknown as BodyInit,
+              // A redirect would re-send the body somewhere the presign did
+              // not authorize.
+              redirect: "manual",
+            }
+          );
+          if (response.status === 412) {
+            observedEtags.delete(spec.key);
+            return { status: "conflict" };
+          }
+          if (!response.ok) {
+            return {
+              status: "error",
+              error: new Error(
+                `cursorHostedFiles: upload of "${spec.key}" failed (HTTP ${response.status})`
+              ),
+            };
+          }
+          const etag = normalizeEtag(response.headers.get("etag"));
+          if (etag !== undefined) {
+            rememberEtag(spec.key, etag);
+          }
+          return { status: "ok", result: etag === undefined ? {} : { etag } };
+        } catch (error) {
+          return { status: "error", error };
+        }
+      })
+    );
+  }
+
+  /**
+   * The full single-key write flow: precondition resolution, one shared
+   * (already-performed) first attempt outcome, and the conflict handling
+   * `put` promises — including the one statKey-and-retry when an optimistic
+   * create loses to an existing object.
+   */
+  async function settlePut(
+    files: FilesTarget,
+    entry: {
+      key: string;
+      body: Uint8Array;
+      options?: { ifMatch?: string | null };
+      cachedEtagUsed?: boolean;
+      staleEtag?: string;
+    },
+    first: UploadOutcome
+  ): Promise<FileSinkPutResult> {
+    if (first.status === "error") {
+      throw first.error;
+    }
+    if (first.status === "ok") {
+      return first.result;
+    }
+    // Conflict. Explicit `ifMatch` (etag or create-only) and cached-etag
+    // writes are single-attempt: the lost precondition is the caller's.
+    const requested = entry.options?.ifMatch;
+    if (requested !== undefined) {
+      throw new FileConflictError(entry.key, {
+        storedEtag: requested ?? undefined,
+      });
+    }
+    if (entry.cachedEtagUsed === true) {
+      // Someone else wrote between our etag observation and this PUT.
+      throw new FileConflictError(entry.key, { storedEtag: entry.staleEtag });
+    }
+    // The optimistic create lost: learn the current etag once and replace.
+    const found = await statKey(entry.key);
+    if (found?.etag === undefined) {
+      // Existed a moment ago (the create lost) but stat sees nothing: a
+      // delete raced this write. Surface the conflict; a retry from the
+      // caller lands on the fresh create-only path.
+      throw new FileConflictError(entry.key, {});
+    }
+    const [replaced] = await attemptUploads(files, [
+      { key: entry.key, body: entry.body, precondition: { etag: found.etag } },
+    ]);
+    if (replaced === undefined || replaced.status === "conflict") {
+      throw new FileConflictError(entry.key, { storedEtag: found?.etag });
+    }
+    if (replaced.status === "error") {
+      throw replaced.error;
+    }
+    return replaced.result;
+  }
+
   /**
-   * Precondition for an unconditional write: replace what is there now, or
-   * create when nothing is.
+   * Precondition for a write, and whether it came from the etag cache (a
+   * cached-etag conflict is terminal; an optimistic-create conflict earns
+   * one stat-and-retry).
    */
-  async function currentPrecondition(
-    key: string
-  ): Promise<{ etag: string } | { new: true }> {
-    const cached = observedEtags.get(key);
+  function preconditionFor(entry: {
+    key: string;
+    options?: { ifMatch?: string | null };
+  }): {
+    precondition: { etag: string } | { new: true };
+    cachedEtagUsed: boolean;
+    staleEtag?: string;
+  } {
+    const requested = entry.options?.ifMatch;
+    // The store rejects unconditional writes, so every put carries a
+    // precondition. `null` is create-only and an explicit etag is a caller
+    // assertion.
+    if (requested !== undefined) {
+      return {
+        precondition: requested === null ? { new: true } : { etag: requested },
+        cachedEtagUsed: false,
+      };
+    }
+    // Unconditional write with a known etag: replace what we saw last.
+    const cached = observedEtags.get(entry.key);
     if (cached !== undefined) {
-      return { etag: cached };
+      return {
+        precondition: { etag: cached },
+        cachedEtagUsed: true,
+        staleEtag: cached,
+      };
     }
-    const found = await statKey(key);
-    // Unknown falls through to create-only. If the object does in fact exist,
-    // the store answers 412 and the caller gets a FileConflictError it can
-    // retry with an explicit `ifMatch` — degraded, but never wrong.
-    return found?.etag === undefined ? { new: true } : { etag: found.etag };
+    // Unconditional write to a key this process has never observed:
+    // create-only first, learning the current etag only on conflict. Most
+    // such writes are brand-new keys (session-event chunks mint a fresh key
+    // per flush), and the old stat-before-every-put shape made the
+    // precondition lookup the single largest source of `agent-serve-files`
+    // list traffic — every fresh pod re-listed a directory per key before
+    // its first write.
+    return { precondition: { new: true }, cachedEtagUsed: false };
   }
 
   return {
@@ -421,84 +708,106 @@ export function cursorHostedFiles(
     capabilities: { etags: true },
 
     async put(key, body, putOptions): Promise<FileSinkPutResult> {
-      const sha = createHash("sha256").update(body).digest("hex");
-      const requested = putOptions?.ifMatch;
-      // The store rejects unconditional writes, so every put carries a
-      // precondition. `null` is create-only and an explicit etag is a caller
-      // assertion; an unconditional write has to learn the current state,
-      // because assuming "absent" would make replace fail on any process that
-      // has not already read the path — which is every fresh pod.
-      const precondition: { etag: string } | { new: true } =
-        requested === null
-          ? { new: true }
-          : requested !== undefined
-            ? { etag: requested }
-            : await currentPrecondition(key);
-
-      return await withFiles(async (files) => {
-        const presigned = await storePost<ApiPresignResponse>(
-          options,
-          files.path("/upload"),
-          {
-            files: [{ path: key, sha, size: body.byteLength, ...precondition }],
-          }
-        );
-        const instruction = presigned.files?.[0];
-        if (instruction?.url === undefined) {
-          // Files past the single-part threshold come back with a multipart
-          // plan instead of a url; this backend does not implement multipart.
-          throw new Error(
-            `cursorHostedFiles: no single-part upload url for "${key}" (too large?)`
-          );
+      return await withFiles(async files => {
+        const entry = { key, body, options: putOptions };
+        const resolved = preconditionFor(entry);
+        const [first] = await attemptUploads(files, [
+          { key, body, precondition: resolved.precondition },
+        ]);
+        if (first === undefined) {
+          throw new Error(`cursorHostedFiles: upload of "${key}" vanished`);
         }
-        const response = await fetchImpl(options)(
-          assertPresignedUrlSafe(options, instruction.url),
+        return await settlePut(
+          files,
           {
-            method: "PUT",
-            headers: instruction.headers ?? {},
-            // A view over bytes is a valid fetch body; the DOM lib types are
-            // narrower than the runtime, and copying into a Blob would double
-            // the memory for every upload.
-            body: body as unknown as BodyInit,
-            // A redirect would re-send the body somewhere the presign did not
-            // authorize.
-            redirect: "manual",
-          }
+            ...entry,
+            cachedEtagUsed: resolved.cachedEtagUsed,
+            staleEtag: resolved.staleEtag,
+          },
+          first
         );
-        if (response.status === 412) {
-          // Someone else wrote between our etag observation and this PUT.
-          observedEtags.delete(key);
-          throw new FileConflictError(key, {
-            ...("etag" in precondition
-              ? { storedEtag: precondition.etag }
-              : {}),
-          });
-        }
-        if (!response.ok) {
-          throw new Error(
-            `cursorHostedFiles: upload of "${key}" failed (HTTP ${response.status})`
+      });
+    },
+
+    async putMany(entries) {
+      if (entries.length === 0) {
+        return [];
+      }
+      return await withFiles(async files => {
+        const resolved = entries.map(entry => ({
+          entry,
+          ...preconditionFor(entry),
+        }));
+        let firsts: UploadOutcome[];
+        try {
+          // One presign call for the whole batch — the point of putMany.
+          firsts = await attemptUploads(
+            files,
+            resolved.map(({ entry, precondition }) => ({
+              key: entry.key,
+              body: entry.body,
+              precondition,
+            }))
           );
+        } catch (error) {
+          // The shared presign failed: every entry failed the same way.
+          return entries.map(() => ({
+            status: "rejected" as const,
+            reason: error,
+          }));
         }
-        const etag = normalizeEtag(response.headers.get("etag"));
-        if (etag !== undefined) {
-          rememberEtag(key, etag);
-        }
-        return etag === undefined ? {} : { etag };
+        return await Promise.all(
+          resolved.map(
+            async (
+              { entry, cachedEtagUsed, staleEtag },
+              index
+            ): Promise<PromiseSettledResult<FileSinkPutResult>> => {
+              const first = firsts[index];
+              if (first === undefined) {
+                return {
+                  status: "rejected",
+                  reason: new Error(
+                    `cursorHostedFiles: upload of "${entry.key}" vanished`
+                  ),
+                };
+              }
+              try {
+                return {
+                  status: "fulfilled",
+                  value: await settlePut(
+                    files,
+                    { ...entry, cachedEtagUsed, staleEtag },
+                    first
+                  ),
+                };
+              } catch (error) {
+                return { status: "rejected", reason: error };
+              }
+            }
+          )
+        );
       });
     },
 
     async get(key): Promise<FileSinkBody | undefined> {
-      return await withFiles(async (files) => {
+      return await withFiles(async files => {
         // Presigning a read of a path the store has no live object for — never
-        // written, or deleted and now holding a tombstone — is a 404. That is
-        // absence, which `read()` reports as undefined, not a failure.
+        // written, or deleted and now holding a tombstone — is a 404 on `/v0`
+        // and an absent entry on the flush wire. Either is absence, which
+        // `read()` reports as undefined, not a failure.
         let presigned: ApiPresignResponse;
         try {
-          presigned = await storePost<ApiPresignResponse>(
-            options,
-            files.path("/download"),
-            { paths: [key] }
-          );
+          presigned =
+            files.wire === "flush"
+              ? await flushPost<ApiPresignResponse>(options, "/read", {
+                  store: files.store,
+                  paths: [key],
+                })
+              : await storePost<ApiPresignResponse>(
+                  options,
+                  files.path("/download"),
+                  { paths: [key] }
+                );
         } catch (error) {
           if (error instanceof StoreApiError && error.status === 404) {
             return undefined;
@@ -548,6 +857,40 @@ export function cursorHostedFiles(
     },
 
     async delete(key): Promise<void> {
+      const handled = await withFiles(async files => {
+        if (files.wire !== "flush") {
+          return false;
+        }
+        // The flush wire's deletes are conditional server-side: when this
+        // process has no observed etag, the server resolves the current one —
+        // the lookup that costs a stat round trip on `/v0` — and a key that
+        // is already absent settles as `already_deleted`.
+        const cached = observedEtags.get(key);
+        const response = await flushPost<FlushWireResponse>(options, "/flush", {
+          store: files.store,
+          ops: [
+            {
+              op: "delete",
+              path: key,
+              ...(cached === undefined ? {} : { etag: cached }),
+            },
+          ],
+        });
+        const outcome = response.ops?.[0];
+        if (outcome?.status === "conflict") {
+          observedEtags.delete(key);
+          throw new FileConflictError(key, {
+            ...(outcome.etag === undefined
+              ? {}
+              : { storedEtag: normalizeEtag(outcome.etag) ?? outcome.etag }),
+          });
+        }
+        observedEtags.delete(key);
+        return true;
+      });
+      if (handled) {
+        return;
+      }
       if (observedEtags.get(key) === undefined) {
         // Deletes are conditional too, so learn the current etag first. A key
         // we have never seen is already absent as far as the caller cares.
@@ -560,7 +903,29 @@ export function cursorHostedFiles(
       if (etag === undefined) {
         return;
       }
-      await withFiles(async (files) => {
+      await withFiles(async files => {
+        if (files.wire === "flush") {
+          // The protocol pin appeared between the two withFiles calls; the
+          // cached etag is enough for the conditional flush delete.
+          const response = await flushPost<FlushWireResponse>(
+            options,
+            "/flush",
+            {
+              store: files.store,
+              ops: [{ op: "delete", path: key, etag }],
+            }
+          );
+          const outcome = response.ops?.[0];
+          if (outcome?.status === "conflict") {
+            observedEtags.delete(key);
+            throw new FileConflictError(key, {
+              ...(outcome.etag === undefined
+                ? {}
+                : { storedEtag: normalizeEtag(outcome.etag) ?? outcome.etag }),
+            });
+          }
+          return;
+        }
         const raw = await storePost<ApiDeleteResponse>(
           options,
           files.path("/delete"),
@@ -568,7 +933,7 @@ export function cursorHostedFiles(
         );
         // The API answers 200 with a per-file status, so a lost race would look
         // like success unless the outcome is read.
-        const outcome = (raw.files ?? []).find((entry) => entry.path === key);
+        const outcome = (raw.files ?? []).find(entry => entry.path === key);
         if (outcome?.status === "conflict") {
           observedEtags.delete(key);
           throw new FileConflictError(key, {
@@ -600,6 +965,13 @@ export function cursorHostedFiles(
  * Same pin as the sibling sync client: production backends allow only the
  * agent-stores bucket hosts, playground its bucket, and a local dev backend
  * additionally admits loopback http for LocalStack.
+ *
+ * `CURSOR_HOSTED_FILES_DEV_PRESIGN_HOSTS` (comma-separated hostnames) admits
+ * extra https hosts. A laptop backend hosting agents on a shared cluster
+ * fronts its LocalStack with a public tunnel and exports this in the pod's
+ * start script; production start scripts never set it. Read once at module
+ * load, so authored agent code sharing this process cannot widen the list
+ * by mutating `process.env` later.
  */
 function assertPresignedUrlSafe(
   options: CursorHostedFilesOptions,
@@ -611,6 +983,14 @@ function assertPresignedUrlSafe(
   } catch {
     throw new Error("cursorHostedFiles: presigned URL is not a valid URL");
   }
+  if (
+    url.protocol === "https:" &&
+    url.username === "" &&
+    url.password === "" &&
+    DEV_PRESIGN_HOSTS.has(url.hostname.toLowerCase())
+  ) {
+    return url.toString();
+  }
   try {
     createAgentStorePresignedUrlValidatorForBackend(resolveBaseUrl(options))(
       url
@@ -665,6 +1045,13 @@ function resolveApiKey(options: CursorHostedFilesOptions): string {
   return key;
 }
 
+const DEV_PRESIGN_HOSTS: ReadonlySet<string> = new Set(
+  (process.env.CURSOR_HOSTED_FILES_DEV_PRESIGN_HOSTS ?? "")
+    .split(",")
+    .map(host => host.trim().toLowerCase())
+    .filter(host => host.length > 0)
+);
+
 function resolveBaseUrl(options: CursorHostedFilesOptions): string {
   return trimTrailingSlash(
     options.baseUrl ??
@@ -706,6 +1093,23 @@ 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.
+ */
+async function flushPost<T>(
+  options: CursorHostedFilesOptions,
+  path: string,
+  body: Record<string, unknown>
+): Promise<T> {
+  return await postJson<T>(
+    options,
+    `${resolveBaseUrl(options)}${AGENTSDK_STORE_PATH}${path}`,
+    body
+  );
+}
+
 async function postJson<T>(
   options: CursorHostedFilesOptions,
   url: string,