@cursor/july 0.1.108 → 0.1.111

package/dist/files-backends/cursor-hosted.js

@@ -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,9 +56,10 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
+var _a;
 import { createHash } from "node:crypto";
 import { FileConflictError, } 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";
 /**
  * Same default as the hosted storage backend, inlined so this entrypoint does
@@ -61,6 +67,15 @@ import { createAgentStorePresignedUrlValidatorForBackend } from "./agent-store-p
  */
 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
@@ -151,15 +166,33 @@ export function cursorHostedFiles(options = {}) {
     /**
      * 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.
      */
     function withFiles(call) {
         return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            var _b;
             const sourceId = resolveStoreSourceId(options);
+            const protocol = (_b = (_a = options.resolveStoreProtocol) === null || _a === void 0 ? void 0 : _a.call(options)) !== null && _b !== void 0 ? _b : 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 yield call({ wire: "flush", store: "framework" });
+                }
+                if (sourceId === resolveDeploymentStoreSourceIdSync()) {
+                    return yield call({ wire: "flush", store: "deployment" });
+                }
+            }
             return yield call({
+                wire: "v0",
                 path: (suffix = "") => `/${encodeURIComponent(sourceId)}${suffix}`,
             });
         });
@@ -167,6 +200,9 @@ export function cursorHostedFiles(options = {}) {
     /** One page of the paginated per-directory listing. */
     function directoryPage(files, directory, pageToken) {
         return __awaiter(this, void 0, void 0, function* () {
+            if (files.wire === "flush") {
+                return yield flushPost(options, "/list", Object.assign({ store: files.store, path: directory, limit: DIRECTORY_PAGE_SIZE }, (pageToken === undefined ? {} : { pageToken })));
+            }
             const query = new URLSearchParams({
                 path: directory,
                 limit: String(DIRECTORY_PAGE_SIZE),
@@ -177,11 +213,22 @@ export function cursorHostedFiles(options = {}) {
             return yield storeGet(options, files.path(`?${query.toString()}`));
         });
     }
+    /** The unscoped whole-store listing, on whichever wire the target rides. */
+    function unscopedListing(files) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (files.wire === "flush") {
+                return yield flushPost(options, "/list", {
+                    store: files.store,
+                });
+            }
+            return yield storeGet(options, files.path());
+        });
+    }
     function listEntries(prefix) {
         return __awaiter(this, void 0, void 0, function* () {
             return yield withFiles((files) => __awaiter(this, void 0, void 0, function* () {
                 var _a;
-                const raw = yield storeGet(options, files.path());
+                const raw = yield unscopedListing(files);
                 if (raw.complete === true) {
                     const out = [];
                     for (const file of (_a = raw.files) !== null && _a !== void 0 ? _a : []) {
@@ -302,78 +349,233 @@ export function cursorHostedFiles(options = {}) {
         });
     }
     /**
-     * Precondition for an unconditional write: replace what is there now, or
-     * create when nothing is.
+     * 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).
      */
-    function currentPrecondition(key) {
+    function presignUploads(files, specs) {
         return __awaiter(this, void 0, void 0, function* () {
-            const cached = observedEtags.get(key);
-            if (cached !== undefined) {
-                return { etag: cached };
+            var _a;
+            if (files.wire === "flush") {
+                const response = yield flushPost(options, "/flush", {
+                    store: files.store,
+                    ops: specs.map(spec => (Object.assign({ 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: ((_a = response.ops) !== null && _a !== void 0 ? _a : []).map(op => (Object.assign(Object.assign({ path: op.path }, (typeof op.url === "string" && op.url !== ""
+                        ? { url: op.url }
+                        : {})), { headers: op.headers }))),
+                };
             }
-            const found = yield 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 === null || found === void 0 ? void 0 : found.etag) === undefined ? { new: true } : { etag: found.etag };
+            return yield storePost(options, files.path("/upload"), {
+                files: specs.map(spec => (Object.assign({ path: spec.key, sha: createHash("sha256").update(spec.body).digest("hex"), size: spec.body.byteLength }, spec.precondition))),
+            });
         });
     }
-    return {
-        // No local copy: bytes live in the store, so `materializedPath()` is
-        // `undefined` and the harness reaches files through `host.files`.
-        capabilities: { etags: true },
-        put(key, body, putOptions) {
-            return __awaiter(this, void 0, void 0, function* () {
-                const sha = createHash("sha256").update(body).digest("hex");
-                const requested = putOptions === null || putOptions === void 0 ? void 0 : 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 = requested === null
-                    ? { new: true }
-                    : requested !== undefined
-                        ? { etag: requested }
-                        : yield currentPrecondition(key);
-                return yield withFiles((files) => __awaiter(this, void 0, void 0, function* () {
-                    var _a;
-                    var _b;
-                    const presigned = yield storePost(options, files.path("/upload"), {
-                        files: [Object.assign({ path: key, sha, size: body.byteLength }, precondition)],
-                    });
-                    const instruction = (_a = presigned.files) === null || _a === void 0 ? void 0 : _a[0];
-                    if ((instruction === null || instruction === void 0 ? void 0 : 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?)`);
-                    }
+    /**
+     * 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.
+     */
+    function attemptUploads(files, specs) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const presigned = yield presignUploads(files, specs);
+            return yield Promise.all(specs.map((spec, index) => __awaiter(this, void 0, void 0, function* () {
+                var _a, _b;
+                var _c, _d;
+                // Match by path, falling back to position for servers that answer
+                // in request order without echoing the path.
+                const instruction = (_c = (_a = presigned.files) === null || _a === void 0 ? void 0 : _a.find(file => file.path === spec.key)) !== null && _c !== void 0 ? _c : (_b = presigned.files) === null || _b === void 0 ? void 0 : _b[index];
+                if ((instruction === null || instruction === void 0 ? void 0 : 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 = yield fetchImpl(options)(assertPresignedUrlSafe(options, instruction.url), {
                         method: "PUT",
-                        headers: (_b = instruction.headers) !== null && _b !== void 0 ? _b : {},
-                        // 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,
-                        // A redirect would re-send the body somewhere the presign did not
-                        // authorize.
+                        headers: (_d = instruction.headers) !== null && _d !== void 0 ? _d : {},
+                        // 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,
+                        // A redirect would re-send the body somewhere the presign did
+                        // not authorize.
                         redirect: "manual",
                     });
                     if (response.status === 412) {
-                        // Someone else wrote between our etag observation and this PUT.
-                        observedEtags.delete(key);
-                        throw new FileConflictError(key, Object.assign({}, ("etag" in precondition
-                            ? { storedEtag: precondition.etag }
-                            : {})));
+                        observedEtags.delete(spec.key);
+                        return { status: "conflict" };
                     }
                     if (!response.ok) {
-                        throw new Error(`cursorHostedFiles: upload of "${key}" failed (HTTP ${response.status})`);
+                        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(key, etag);
+                        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.
+     */
+    function settlePut(files, entry, first) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            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 = (_a = entry.options) === null || _a === void 0 ? void 0 : _a.ifMatch;
+            if (requested !== undefined) {
+                throw new FileConflictError(entry.key, {
+                    storedEtag: requested !== null && requested !== void 0 ? 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 = yield statKey(entry.key);
+            if ((found === null || found === void 0 ? void 0 : 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] = yield 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 === null || found === void 0 ? void 0 : found.etag });
+            }
+            if (replaced.status === "error") {
+                throw replaced.error;
+            }
+            return replaced.result;
+        });
+    }
+    /**
+     * 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).
+     */
+    function preconditionFor(entry) {
+        var _a;
+        const requested = (_a = entry.options) === null || _a === void 0 ? void 0 : _a.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 {
+                precondition: { etag: cached },
+                cachedEtagUsed: true,
+                staleEtag: cached,
+            };
+        }
+        // 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 {
+        // No local copy: bytes live in the store, so `materializedPath()` is
+        // `undefined` and the harness reaches files through `host.files`.
+        capabilities: { etags: true },
+        put(key, body, putOptions) {
+            return __awaiter(this, void 0, void 0, function* () {
+                return yield withFiles((files) => __awaiter(this, void 0, void 0, function* () {
+                    const entry = { key, body, options: putOptions };
+                    const resolved = preconditionFor(entry);
+                    const [first] = yield attemptUploads(files, [
+                        { key, body, precondition: resolved.precondition },
+                    ]);
+                    if (first === undefined) {
+                        throw new Error(`cursorHostedFiles: upload of "${key}" vanished`);
+                    }
+                    return yield settlePut(files, Object.assign(Object.assign({}, entry), { cachedEtagUsed: resolved.cachedEtagUsed, staleEtag: resolved.staleEtag }), first);
+                }));
+            });
+        },
+        putMany(entries) {
+            return __awaiter(this, void 0, void 0, function* () {
+                if (entries.length === 0) {
+                    return [];
+                }
+                return yield withFiles((files) => __awaiter(this, void 0, void 0, function* () {
+                    const resolved = entries.map(entry => (Object.assign({ entry }, preconditionFor(entry))));
+                    let firsts;
+                    try {
+                        // One presign call for the whole batch — the point of putMany.
+                        firsts = yield 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",
+                            reason: error,
+                        }));
                     }
-                    return etag === undefined ? {} : { etag };
+                    return yield Promise.all(resolved.map((_a, index_1) => __awaiter(this, [_a, index_1], void 0, function* ({ entry, cachedEtagUsed, staleEtag }, index) {
+                        const first = firsts[index];
+                        if (first === undefined) {
+                            return {
+                                status: "rejected",
+                                reason: new Error(`cursorHostedFiles: upload of "${entry.key}" vanished`),
+                            };
+                        }
+                        try {
+                            return {
+                                status: "fulfilled",
+                                value: yield settlePut(files, Object.assign(Object.assign({}, entry), { cachedEtagUsed, staleEtag }), first),
+                            };
+                        }
+                        catch (error) {
+                            return { status: "rejected", reason: error };
+                        }
+                    })));
                 }));
             });
         },
@@ -382,11 +584,18 @@ export function cursorHostedFiles(options = {}) {
                 return yield withFiles((files) => __awaiter(this, void 0, void 0, function* () {
                     var _a, _b;
                     // 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;
                     try {
-                        presigned = yield storePost(options, files.path("/download"), { paths: [key] });
+                        presigned =
+                            files.wire === "flush"
+                                ? yield flushPost(options, "/read", {
+                                    store: files.store,
+                                    paths: [key],
+                                })
+                                : yield storePost(options, files.path("/download"), { paths: [key] });
                     }
                     catch (error) {
                         if (error instanceof StoreApiError && error.status === 404) {
@@ -430,6 +639,36 @@ export function cursorHostedFiles(options = {}) {
         },
         delete(key) {
             return __awaiter(this, void 0, void 0, function* () {
+                const handled = yield withFiles((files) => __awaiter(this, void 0, void 0, function* () {
+                    var _a;
+                    var _b;
+                    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 = yield flushPost(options, "/flush", {
+                        store: files.store,
+                        ops: [
+                            Object.assign({ op: "delete", path: key }, (cached === undefined ? {} : { etag: cached })),
+                        ],
+                    });
+                    const outcome = (_a = response.ops) === null || _a === void 0 ? void 0 : _a[0];
+                    if ((outcome === null || outcome === void 0 ? void 0 : outcome.status) === "conflict") {
+                        observedEtags.delete(key);
+                        throw new FileConflictError(key, Object.assign({}, (outcome.etag === undefined
+                            ? {}
+                            : { storedEtag: (_b = normalizeEtag(outcome.etag)) !== null && _b !== void 0 ? _b : 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.
@@ -443,16 +682,33 @@ export function cursorHostedFiles(options = {}) {
                     return;
                 }
                 yield withFiles((files) => __awaiter(this, void 0, void 0, function* () {
-                    var _a, _b;
+                    var _a;
+                    var _b, _c, _d;
+                    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 = yield flushPost(options, "/flush", {
+                            store: files.store,
+                            ops: [{ op: "delete", path: key, etag }],
+                        });
+                        const outcome = (_a = response.ops) === null || _a === void 0 ? void 0 : _a[0];
+                        if ((outcome === null || outcome === void 0 ? void 0 : outcome.status) === "conflict") {
+                            observedEtags.delete(key);
+                            throw new FileConflictError(key, Object.assign({}, (outcome.etag === undefined
+                                ? {}
+                                : { storedEtag: (_b = normalizeEtag(outcome.etag)) !== null && _b !== void 0 ? _b : outcome.etag })));
+                        }
+                        return;
+                    }
                     const raw = yield storePost(options, files.path("/delete"), { files: [{ path: key, etag }] });
                     // The API answers 200 with a per-file status, so a lost race would look
                     // like success unless the outcome is read.
-                    const outcome = ((_a = raw.files) !== null && _a !== void 0 ? _a : []).find((entry) => entry.path === key);
+                    const outcome = ((_c = raw.files) !== null && _c !== void 0 ? _c : []).find(entry => entry.path === key);
                     if ((outcome === null || outcome === void 0 ? void 0 : outcome.status) === "conflict") {
                         observedEtags.delete(key);
                         throw new FileConflictError(key, Object.assign({}, (outcome.etag === undefined
                             ? {}
-                            : { storedEtag: (_b = normalizeEtag(outcome.etag)) !== null && _b !== void 0 ? _b : outcome.etag })));
+                            : { storedEtag: (_d = normalizeEtag(outcome.etag)) !== null && _d !== void 0 ? _d : outcome.etag })));
                     }
                 }));
                 observedEtags.delete(key);
@@ -477,6 +733,13 @@ export function cursorHostedFiles(options = {}) {
  * 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, raw) {
     let url;
@@ -486,6 +749,12 @@ function assertPresignedUrlSafe(options, raw) {
     catch (_a) {
         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);
     }
@@ -528,6 +797,10 @@ function resolveApiKey(options) {
     }
     return key;
 }
+const DEV_PRESIGN_HOSTS = new Set(((_a = process.env.CURSOR_HOSTED_FILES_DEV_PRESIGN_HOSTS) !== null && _a !== void 0 ? _a : "")
+    .split(",")
+    .map(host => host.trim().toLowerCase())
+    .filter(host => host.length > 0));
 function resolveBaseUrl(options) {
     var _a, _b;
     return trimTrailingSlash((_b = (_a = options.baseUrl) !== null && _a !== void 0 ? _a : process.env.CURSOR_API_BASE_URL) !== null && _b !== void 0 ? _b : DEFAULT_CURSOR_EXTERNAL_API_URL);
@@ -551,6 +824,16 @@ function storeGet(options, path) {
         return yield sendJson(options, `${resolveBaseUrl(options)}${AGENT_SERVE_FILES_PATH}${path}`, "GET");
     });
 }
+/**
+ * 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.
+ */
+function flushPost(options, path, body) {
+    return __awaiter(this, void 0, void 0, function* () {
+        return yield postJson(options, `${resolveBaseUrl(options)}${AGENTSDK_STORE_PATH}${path}`, body);
+    });
+}
 function postJson(options, url, body) {
     return __awaiter(this, void 0, void 0, function* () {
         return yield sendJson(options, url, "POST", body);

package/dist/files-backends/local-fs.js

@@ -84,7 +84,7 @@ export function localFiles(options) {
     });
     return {
         capabilities: { materialized: true },
-        materializedPath: (key) => pathForKey(key),
+        materializedPath: key => pathForKey(key),
         put(key, body) {
             return __awaiter(this, void 0, void 0, function* () {
                 const target = pathForKey(key);

package/dist/files.d.ts

@@ -75,6 +75,21 @@ export interface FileSink {
     put(key: string, body: Uint8Array, options?: {
         ifMatch?: string | null;
     }): Promise<FileSinkPutResult | void>;
+    /**
+     * Write several values in one round trip where the backend can (one
+     * presign call instead of one per key). Optional — callers fall back to
+     * sequential {@link put}. Outcomes are settled per entry, index-aligned
+     * with the input: one key's conflict or failure never rejects its batch
+     * siblings. Per-key semantics (preconditions, conflict errors, etag
+     * bookkeeping) match {@link put} exactly.
+     */
+    putMany?(entries: Array<{
+        key: string;
+        body: Uint8Array;
+        options?: {
+            ifMatch?: string | null;
+        };
+    }>): Promise<Array<PromiseSettledResult<FileSinkPutResult | void>>>;
     /** Read one value. Miss → `undefined`. */
     get(key: string): Promise<FileSinkBody | Uint8Array | undefined>;
     /** Remove one key. No-op when missing. */

package/dist/files.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"files.d.ts","sourceRoot":"","sources":["../src/files.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"files.d.ts","sourceRoot":"","sources":["../src/files.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAQH,mDAAmD;AACnD,MAAM,WAAW,aAAa;IAC5B,+DAA+D;IAC/D,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+DAA+D;IAC/D,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,wDAAwD;AACxD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,UAAU,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,uCAAuC;AACvC,MAAM,WAAW,iBAAiB;IAChC,6DAA6D;IAC7D,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,gDAAgD;IAChD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACvB;;;;;OAKG;IACH,GAAG,CACD,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,UAAU,EAChB,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GACpC,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAC;IACrC;;;;;;;OAOG;IACH,OAAO,CAAC,CACN,OAAO,EAAE,KAAK,CAAC;QACb,GAAG,EAAE,MAAM,CAAC;QACZ,IAAI,EAAE,UAAU,CAAC;QACjB,OAAO,CAAC,EAAE;YAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;SAAE,CAAC;KACvC,CAAC,GACD,OAAO,CAAC,KAAK,CAAC,oBAAoB,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IAClE,0CAA0C;IAC1C,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,UAAU,GAAG,SAAS,CAAC,CAAC;IACjE,0CAA0C;IAC1C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,4DAA4D;IAC5D,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;IAC/C,wFAAwF;IACxF,IAAI,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAAC;IACvD;;;;OAIG;IACH,gBAAgB,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACnD,YAAY,CAAC,EAAE,oBAAoB,CAAC;CACrC;AAMD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,QAAQ;aACnB,UAAU,UAAU,MAAM,QAAQ,MAAM,KAAG,MAAM;aAEjD,mBAAmB,UACV,MAAM,aACF,MAAM,QACX,MAAM,KACX,MAAM;aAET,OAAO,UAAU,MAAM,aAAa,MAAM,QAAQ,MAAM,KAAG,MAAM;aAEjE,gBAAgB,UAAU,MAAM,KAAG,MAAM;aAEzC,aAAa,UAAU,MAAM,aAAa,MAAM,KAAG,MAAM;CAEjD,CAAC;AAEX;;;;GAIG;AACH,eAAO,MAAM,sCAAsC,SAAS,CAAC;AAE7D;;;GAGG;AACH,eAAO,MAAM,iCAAiC,gBAAgB,CAAC;AAE/D;;;;;;;;;;;;;;GAcG;AACH,iBAAS,oBAAoB,CAAC,IAAI,EAAE,MAAM;aAEtC,WAAW,UAAU,MAAM,MAAM,MAAM,KAAG,MAAM;aAEhD,iBAAiB,UAAU,MAAM,KAAG,MAAM;aAE1C,eAAe,UAAU,MAAM,MAAM,MAAM,KAAG,MAAM;aAEpD,SAAS,cACI,MAAM,WACR,MAAM,iBACD,MAAM,KACnB,MAAM;aACT,YAAY,QAAM,MAAM;IACxB,kGAAkG;aAClG,gBAAgB,UAAU,MAAM,KAAG,MAAM;aAEzC,aAAa,YACF,MAAM,oBACE,MAAM,KACtB,MAAM;aACT,eAAe,QAAM,MAAM;IAC3B,2EAA2E;aAC3E,mBAAmB,UAAU,MAAM,KAAG,MAAM;aAE5C,sBAAsB,cAAc,MAAM,KAAG,MAAM;IAEnD,iFAAiF;aACjF,0BAA0B,UAAU,MAAM,aAAa,MAAM,KAAG,MAAM;aAEtE,SAAS,UAAU,MAAM,KAAG,MAAM;aAClC,aAAa,UAAU,MAAM,KAAG,MAAM;aAEtC,oBAAoB,UAAU,MAAM,SAAS,MAAM,KAAG,MAAM;aAK5D,oBAAoB,UAAU,MAAM,cAAc,MAAM,KAAG,MAAM;aAEjE,gBAAgB,UACP,MAAM,cACD,MAAM,UACV,MAAM,KACb,MAAM;EAGZ;AAED,MAAM,MAAM,cAAc,GAAG,UAAU,CAAC,OAAO,oBAAoB,CAAC,CAAC;AACrE,eAAO,MAAM,cAAc,EAAE,cACW,CAAC;AACzC,eAAO,MAAM,sBAAsB,EAAE,cAEpC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,8BAA8B,CAAC;AAEvE;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,wBAAwB,CAAC;AAE3D,+EAA+E;AAC/E,qBAAa,iBAAkB,SAAQ,KAAK;IAExC,QAAQ,CAAC,GAAG,EAAE,MAAM;IADtB,YACW,GAAG,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,EAgBnD;IACD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,sDAAsD;AACtD,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AAED,sDAAsD;AACtD,qBAAa,wBAAyB,SAAQ,KAAK;IACjD,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AAED,4CAA4C;AAC5C,qBAAa,iBAAkB,SAAQ,KAAK;IAExC,QAAQ,CAAC,GAAG,EAAE,MAAM;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM;IAH3B,YACW,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAM1B;CACF"}