@cursor/bdk 0.2.1

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

@@ -0,0 +1,978 @@
+/**
+ * Cursor-managed durable files for hosted agents — the backend that puts
+ * `ctx.host.files` bytes in an Agent Store on S3.
+ *
+ * One credential throughout: the engine's pod `CURSOR_API_KEY`. It authorizes
+ * every call, and the bytes then move between this process and presigned S3
+ * URLs. File contents never transit the control plane, so a large artifact
+ * costs S3 bandwidth rather than backend memory.
+ *
+ * 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
+ * credential needs (an in-pod FUSE daemon). This process holds the credential
+ * the token would be minted from, so a token bought a round trip, an expiry to
+ * manage, and a second auth path, and no privilege reduction. And there is no
+ * direct call to the store service: the API layer owns the policy, and the
+ * engine never addresses it.
+ *
+ * There is also no store lookup. Every request names this deployment's file
+ * store by the `agentStoreSourceId` the deploy pipeline pinned into the pod
+ * env as `AGENT_SERVE_STORE_SOURCE_ID` — provisioning the store at the same
+ * time, so by boot the store exists and the id resolves. The id is an
+ * address, not a credential: the server maps it to a store and authorizes
+ * every call against the deployment's own live service account, so holding
+ * it grants nothing, and this process never learns a store id it could use
+ * to ask for anyone else's.
+ *
+ * Locally, point `CURSOR_API_BASE_URL` at a backend that serves
+ * `/v0/agent-serve-files` and use a deployment SA key; off hosting the
+ * local-disk sink is the default instead.
+ *
+ * Writes are conditional. The store rejects unconditional writes, so every
+ * `put` first learns the current etag: `new` for a path we believe is absent,
+ * `etag` to replace what we last observed. A raced write comes back 412 and
+ * surfaces as {@link FileConflictError}, which is why this backend reports
+ * `etags: true` and `host.files.capabilities.conflictDetection` is honestly
+ * true.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var _a;
+import { createHash } from "node:crypto";
+import { FileConflictError, } from "../files.js";
+import { mapBounded } from "../internal/bounded.js";
+import { 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";
+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
+ * user secrets. Its presence is the signal that a durable store exists and
+ * the hosted control plane is reachable; a deployment without one (no
+ * service account yet) has no store, and this backend is not selected.
+ */
+export const AGENT_SERVE_STORE_SOURCE_ID_ENV_VAR = "AGENT_SERVE_STORE_SOURCE_ID";
+/**
+ * The deployment's **framework-level** file store, distinct from the
+ * user-level store above. The user store carries author-facing bytes
+ * (`ctx.host.files`, skills, memory, artifacts) and is browsable and
+ * mountable; the framework store carries engine-owned session state —
+ * session records, event transcripts, hosted-execution run logs,
+ * continuation index, and the SDK conversation mirror — and is never
+ * exposed to authors or models.
+ * Provisioned by the v2 deploy pipeline alongside the user store; v1
+ * deployments have only the user store.
+ */
+export const AGENT_SERVE_FRAMEWORK_STORE_SOURCE_ID_ENV_VAR = "AGENT_SERVE_FRAMEWORK_STORE_SOURCE_ID";
+/** Cap on the per-process etag cache; a miss costs a lookup, not correctness. */
+const MAX_REMEMBERED_ETAGS = 1000;
+/** Bounded directory page for point lookups. */
+const DIRECTORY_PAGE_SIZE = 1000;
+/**
+ * Paths per presign call in {@link FileSink.getMany}, matching the factory
+ * `/read` route's server-side `MAX_READ_PATHS`. The whole point of the batch:
+ * the factory wire's per-deployment rate limiter counts requests, not files,
+ * so a restore that used to spend N `/read` calls now spends ceil(N/100).
+ */
+const READ_PRESIGN_BATCH_MAX = 100;
+/**
+ * Concurrent presigned-URL downloads inside one {@link FileSink.getMany}
+ * batch — the S3 fan-out, not the control-plane call count. Matches the
+ * conversation mirror's historical `HYDRATE_DOWNLOAD_CONCURRENCY`.
+ */
+const GET_MANY_DOWNLOAD_CONCURRENCY = 8;
+/** Stop paging a pathological directory rather than scanning forever. */
+const MAX_DIRECTORY_PAGES = 20;
+/**
+ * Total page budget for a full `list()` walk of a store the unscoped listing
+ * could not carry (~1M entries at the page size above). Past it, fail loudly:
+ * a silently partial listing would be mistaken for the whole scope.
+ */
+const MAX_LIST_WALK_PAGES = 1000;
+/**
+ * True on Cursor-managed hosting with a provisioned file store.
+ *
+ * Keyed on the store source id alone, deliberately: the credential is not part
+ * of the test. If it were, a missing or regressed `CURSOR_API_KEY` would
+ * silently select pod-local disk on a hosted pod and accept writes that vanish
+ * with the pod. Instead the store is detected, and a missing credential fails
+ * loudly when the sink is used.
+ */
+export function isCursorHostedFilesAvailable(env = process.env) {
+    return resolveDeploymentStoreSourceIdSync(env) !== undefined;
+}
+/**
+ * Local `serve`/`run` with a personal `CURSOR_API_KEY` can address
+ * `/v0/agent-serve-files/user`. Hosted deployments have a store source id
+ * and must not take this path — they own the deployment store instead.
+ */
+export function isCursorUserStoreFilesAvailable(env = process.env) {
+    var _a;
+    if (isCursorHostedFilesAvailable(env)) {
+        return false;
+    }
+    // Vitest inherits the developer's shell. User-store sync writes durable
+    // keys; skip it in the test runner so `pnpm test` cannot poison
+    // `agent-serve/<agent>/skills/` on the caller's USER store.
+    if (env.VITEST === "true") {
+        return false;
+    }
+    const key = (_a = env.CURSOR_API_KEY) === null || _a === void 0 ? void 0 : _a.trim();
+    return key !== undefined && key !== "";
+}
+/**
+ * Cursor-hosted {@link FileSink}, selected on Cursor-managed hosting.
+ *
+ * Stateless apart from the etag cache below: every request names this
+ * deployment's store by its pinned source id, so there is nothing to
+ * resolve, hold, or invalidate.
+ */
+export function cursorHostedFiles(options = {}) {
+    /**
+     * Etags observed per key, so a replace can carry a precondition without
+     * re-reading. Bounded: a resident engine is long-lived and touches an
+     * unbounded number of keys over its lifetime. Oldest-out is fine — a miss
+     * costs one lookup, not correctness.
+     */
+    const observedEtags = new Map();
+    const rememberEtag = (key, etag) => {
+        if (observedEtags.size >= MAX_REMEMBERED_ETAGS) {
+            const oldest = observedEtags.keys().next();
+            if (!oldest.done) {
+                observedEtags.delete(oldest.value);
+            }
+        }
+        observedEtags.set(key, etag);
+    };
+    /**
+     * Run `call` against this deployment's files.
+     *
+     * 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 (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
+                // 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}`,
+            });
+        });
+    }
+    /**
+     * Fetch one presigned read URL, shared by `get` and `getMany`. A 404 on
+     * the object GET is absence (a delete raced the presign).
+     *
+     * A 403 here is deliberately *not* absence. Absence was already settled
+     * by the presign: the store refuses to presign a path with no live
+     * object, so reaching this point means the object existed moments ago.
+     * What produces a 403 after a good presign is an expired or clock-skewed
+     * signature, a policy change, or a delete that raced the GET — all
+     * transient or retryable, none of them "definitively gone".
+     *
+     * Reporting them as absence is how a store blip becomes data loss:
+     * `undefined` on a continuation read is taken as "unknown token", and
+     * the engine mints a fresh session under it, forking the thread. The
+     * delete race resolves itself on retry, where the presign returns 404
+     * and this correctly reads as a miss.
+     */
+    function downloadPresigned(key, url) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const response = yield resolveCursorApiFetch(options)(assertPresignedUrlSafe(options, url), {
+                method: "GET",
+                redirect: "manual",
+            });
+            if (response.status === 404) {
+                return undefined;
+            }
+            if (!response.ok) {
+                throw new Error(`cursorHostedFiles: download of "${key}" failed (HTTP ${response.status})`);
+            }
+            const etag = normalizeEtag(response.headers.get("etag"));
+            if (etag !== undefined) {
+                rememberEtag(key, etag);
+            }
+            return Object.assign({ body: new Uint8Array(yield response.arrayBuffer()) }, (etag === undefined ? {} : { etag }));
+        });
+    }
+    /** 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),
+            });
+            if (pageToken !== undefined) {
+                query.set("pageToken", pageToken);
+            }
+            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 unscopedListing(files);
+                if (raw.complete === true) {
+                    const out = [];
+                    for (const file of (_a = raw.files) !== null && _a !== void 0 ? _a : []) {
+                        if (typeof file.path !== "string" || !file.path.startsWith(prefix)) {
+                            continue;
+                        }
+                        out.push(toEntry(file, file.path));
+                    }
+                    // The FileSink contract promises key order, and transcript-chunk
+                    // consumers depend on it (chunk keys are zero-padded so key order
+                    // is append order). The server happens to scan in order today; do
+                    // not let that be the only thing holding the contract.
+                    return out.sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+                }
+                // The unscoped listing was truncated (`complete: false`) and has no
+                // continuation to follow. `list()` promises the whole scope, so rather
+                // than lie or fail, walk the paginated per-directory form, which does
+                // paginate and reports immediate subdirectories to recurse into.
+                return yield walkDirectoryTree(files, prefix);
+            }));
+        });
+    }
+    /**
+     * Every entry under `prefix`, via the paginated directory listing.
+     *
+     * Starts at the deepest directory the prefix fully names and descends only
+     * into subdirectories that can still hold matches. Bounded so a runaway
+     * store fails loudly rather than returning a silently partial answer the
+     * caller would mistake for the whole scope.
+     */
+    function walkDirectoryTree(files, prefix) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
+            const slash = prefix.lastIndexOf("/");
+            const pending = [slash === -1 ? "" : prefix.slice(0, slash)];
+            const queued = new Set(pending);
+            const out = [];
+            let pageBudget = MAX_LIST_WALK_PAGES;
+            while (pending.length > 0) {
+                const directory = pending.pop();
+                let pageToken;
+                do {
+                    if (pageBudget <= 0) {
+                        throw new Error("cursorHostedFiles: the store is too large to list; scope the listing with a narrower prefix");
+                    }
+                    pageBudget -= 1;
+                    const page = yield directoryPage(files, directory, pageToken);
+                    for (const file of (_a = page.files) !== null && _a !== void 0 ? _a : []) {
+                        if (typeof file.path === "string" && file.path.startsWith(prefix)) {
+                            out.push(toEntry(file, file.path));
+                        }
+                    }
+                    // Every page can surface different subdirectories, so collect from
+                    // all of them, deduped — and descend only into branches that can
+                    // still hold matches: a descendant of the prefix, or (at the first
+                    // level) a directory the prefix's basename component narrows to.
+                    for (const subdir of (_b = page.directories) !== null && _b !== void 0 ? _b : []) {
+                        if (queued.has(subdir)) {
+                            continue;
+                        }
+                        if (`${subdir}/`.startsWith(prefix) || prefix.startsWith(`${subdir}/`)) {
+                            queued.add(subdir);
+                            pending.push(subdir);
+                        }
+                    }
+                    pageToken =
+                        page.complete === false && page.nextPageToken !== undefined
+                            ? page.nextPageToken
+                            : undefined;
+                } while (pageToken !== undefined);
+            }
+            return out.sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+        });
+    }
+    /** Shared decode: remember the etag as a side effect, then shape the entry. */
+    function toEntry(file, key) {
+        if (typeof file.etag === "string" && file.etag !== "") {
+            rememberEtag(key, file.etag);
+        }
+        const mtimeMs = typeof file.updatedAt === "string" ? Date.parse(file.updatedAt) : undefined;
+        return Object.assign(Object.assign({ key, size: typeof file.sizeBytes === "number" ? file.sizeBytes : 0 }, (typeof file.etag === "string" && file.etag !== "" ? { etag: file.etag } : {})), (mtimeMs === undefined || Number.isNaN(mtimeMs) ? {} : { mtimeMs }));
+    }
+    /**
+     * One key's current entry, via the bounded directory listing.
+     *
+     * The unscoped listing has no prefix parameter, so using it for a point lookup
+     * would walk the whole store on the hot write path and cost more the fuller
+     * the store got. `?path=` is scoped to one directory and paginates, and the
+     * scan stops as soon as the key appears.
+     */
+    function statKey(key) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const slash = key.lastIndexOf("/");
+            const directory = slash === -1 ? "" : key.slice(0, slash);
+            return yield withFiles((files) => __awaiter(this, void 0, void 0, function* () {
+                var _a;
+                let pageToken;
+                for (let page = 0; page < MAX_DIRECTORY_PAGES; page += 1) {
+                    const raw = yield directoryPage(files, directory, pageToken);
+                    for (const file of (_a = raw.files) !== null && _a !== void 0 ? _a : []) {
+                        if (file.path === key) {
+                            return toEntry(file, key);
+                        }
+                    }
+                    // `complete` is false exactly when another page is waiting.
+                    if (raw.complete !== false || raw.nextPageToken === undefined) {
+                        return undefined;
+                    }
+                    pageToken = raw.nextPageToken;
+                }
+                return undefined;
+            }));
+        });
+    }
+    /**
+     * 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 presignUploads(files, specs) {
+        return __awaiter(this, void 0, void 0, function* () {
+            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 }))),
+                };
+            }
+            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))),
+            });
+        });
+    }
+    /**
+     * 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 resolveCursorApiFetch(options)(assertPresignedUrlSafe(options, instruction.url), {
+                        method: "PUT",
+                        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) {
+                        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.
+     */
+    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 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 };
+                        }
+                    })));
+                }));
+            });
+        },
+        get(key) {
+            return __awaiter(this, void 0, void 0, function* () {
+                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 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 =
+                            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) {
+                            return undefined;
+                        }
+                        throw error;
+                    }
+                    const url = (_b = (_a = presigned.files) === null || _a === void 0 ? void 0 : _a[0]) === null || _b === void 0 ? void 0 : _b.url;
+                    if (url === undefined) {
+                        return undefined;
+                    }
+                    return yield downloadPresigned(key, url);
+                }));
+            });
+        },
+        getMany(keys) {
+            return __awaiter(this, void 0, void 0, function* () {
+                if (keys.length === 0) {
+                    return [];
+                }
+                const bodies = yield withFiles((files) => __awaiter(this, void 0, void 0, function* () {
+                    var _a;
+                    if (files.wire !== "flush") {
+                        // `/v0` presigns 404 the whole batch when any path is absent, so a
+                        // batched call cannot tell one missing key from a failed request.
+                        // Bounded per-key gets keep the `/v0` absence semantics exact; the
+                        // batch win belongs to the flush wire, whose contract is "an absent
+                        // path is an absent entry" — and whose per-deployment rate limiter
+                        // is the reason to spend fewer requests in the first place.
+                        return yield mapBounded([...keys], GET_MANY_DOWNLOAD_CONCURRENCY, (key) => __awaiter(this, void 0, void 0, function* () {
+                            var _a, _b;
+                            const presigned = yield storePost(options, files.path("/download"), { paths: [key] }).catch((error) => {
+                                if (error instanceof StoreApiError && error.status === 404) {
+                                    return undefined;
+                                }
+                                throw error;
+                            });
+                            const url = (_b = (_a = presigned === null || presigned === void 0 ? void 0 : presigned.files) === null || _a === void 0 ? void 0 : _a[0]) === null || _b === void 0 ? void 0 : _b.url;
+                            if (url === undefined) {
+                                return undefined;
+                            }
+                            return yield downloadPresigned(key, url);
+                        }));
+                    }
+                    const urls = new Map();
+                    for (let from = 0; from < keys.length; from += READ_PRESIGN_BATCH_MAX) {
+                        const chunk = keys.slice(from, from + READ_PRESIGN_BATCH_MAX);
+                        let presigned;
+                        try {
+                            presigned = yield flushPost(options, "/read", {
+                                store: files.store,
+                                paths: chunk,
+                            });
+                        }
+                        catch (error) {
+                            if (error instanceof StoreApiError && error.status === 404) {
+                                // The read route never 404s per path (absent paths are
+                                // omitted entries); a 404 is the store itself — not
+                                // provisioned, or deleted under us — which get() reads as
+                                // absence for every key.
+                                return keys.map(() => undefined);
+                            }
+                            throw error;
+                        }
+                        for (const entry of (_a = presigned.files) !== null && _a !== void 0 ? _a : []) {
+                            if (entry.path !== undefined && entry.url !== undefined) {
+                                urls.set(entry.path, entry.url);
+                            }
+                        }
+                    }
+                    return yield mapBounded([...keys], GET_MANY_DOWNLOAD_CONCURRENCY, (key) => __awaiter(this, void 0, void 0, function* () {
+                        var _a, _b;
+                        const url = urls.get(key);
+                        if (url !== undefined) {
+                            return yield downloadPresigned(key, url);
+                        }
+                        // A miss in the batch is NOT yet a definitive absence: the
+                        // server echoes each path *normalized* (trimmed, backslashes
+                        // folded, empty/"." segments dropped), so a key whose
+                        // normalized form differs from what was sent never matches the
+                        // echo even though its object exists. `get()` is immune (it
+                        // reads the response positionally), so settle every batch miss
+                        // through the single-path read — keeping getMany's absence
+                        // semantics byte-identical to get()'s. Genuine absences pay one
+                        // extra request; every batch caller reads keys it just listed
+                        // or was told exist, so real misses are rare (delete races,
+                        // store loss).
+                        const presigned = yield flushPost(options, "/read", {
+                            store: files.store,
+                            paths: [key],
+                        }).catch((error) => {
+                            // Store-level 404 (deleted between the batch and this read):
+                            // absence, same as get().
+                            if (error instanceof StoreApiError && error.status === 404) {
+                                return undefined;
+                            }
+                            throw error;
+                        });
+                        const singleUrl = (_b = (_a = presigned === null || presigned === void 0 ? void 0 : presigned.files) === null || _a === void 0 ? void 0 : _a[0]) === null || _b === void 0 ? void 0 : _b.url;
+                        if (singleUrl === undefined) {
+                            return undefined;
+                        }
+                        return yield downloadPresigned(key, singleUrl);
+                    }));
+                }));
+                return bodies;
+            });
+        },
+        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.
+                    const found = yield statKey(key);
+                    if ((found === null || found === void 0 ? void 0 : found.etag) === undefined) {
+                        return;
+                    }
+                }
+                const etag = observedEtags.get(key);
+                if (etag === undefined) {
+                    return;
+                }
+                yield withFiles((files) => __awaiter(this, void 0, void 0, function* () {
+                    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 = ((_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: (_d = normalizeEtag(outcome.etag)) !== null && _d !== void 0 ? _d : outcome.etag })));
+                    }
+                }));
+                observedEtags.delete(key);
+            });
+        },
+        list: listEntries,
+        stat(key) {
+            return __awaiter(this, void 0, void 0, function* () {
+                return yield statKey(key);
+            });
+        },
+    };
+}
+/**
+ * Refuse a presigned URL that does not target this backend's agent-stores
+ * bucket.
+ *
+ * The URL arrives from BCS over TLS, so this is defense in depth rather than
+ * a live hole — but the engine pod can reach link-local metadata and other
+ * allowlisted egress hosts, so a BCS bug or compromise returning a foreign
+ * address would otherwise steer file bytes somewhere the caller never chose.
+ * 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;
+    try {
+        url = new URL(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(resolveCursorApiBaseUrl(options))(url);
+    }
+    catch (error) {
+        throw new Error(`cursorHostedFiles: refused presigned URL: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return url.toString();
+}
+/**
+ * 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.
+ *
+ * Fails loudly rather than defaulting: with no source id there is no store to
+ * address, and writing somewhere else silently is worse than not writing.
+ */
+function resolveStoreSourceId(options) {
+    var _a, _b;
+    var _c, _d;
+    const id = (_b = ((_d = (_c = (_a = options.resolveStoreSourceId) === null || _a === void 0 ? void 0 : _a.call(options)) !== null && _c !== void 0 ? _c : options.storeSourceId) !== null && _d !== void 0 ? _d : resolveDeploymentStoreSourceIdSync(process.env))) === null || _b === void 0 ? void 0 : _b.trim();
+    if (id === undefined || id === "") {
+        throw new Error(`cursorHostedFiles requires ${AGENT_SERVE_STORE_SOURCE_ID_ENV_VAR} (set on Cursor-managed deployments)`);
+    }
+    return id;
+}
+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));
+/**
+ * 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
+ * against the store's live owner. There is no second, narrower credential.
+ */
+function storePost(options, path, body) {
+    return __awaiter(this, void 0, void 0, function* () {
+        return yield postJson(options, `${resolveCursorApiBaseUrl(options)}${AGENT_SERVE_FILES_PATH}${path}`, body);
+    });
+}
+function storeGet(options, path) {
+    return __awaiter(this, void 0, void 0, function* () {
+        return yield sendJson(options, `${resolveCursorApiBaseUrl(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. The
+ * domain-call lane one path family deeper is NOT here: it belongs to the
+ * store API client (`../internal/cursor/store-api-client.ts`).
+ */
+function flushPost(options, path, body) {
+    return __awaiter(this, void 0, void 0, function* () {
+        return yield postJson(options, `${resolveCursorApiBaseUrl(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);
+    });
+}
+function sendJson(options, url, method, body) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const response = yield resolveCursorApiFetch(options)(url, Object.assign({ method, headers: Object.assign({ Authorization: `Bearer ${resolveCursorApiKey(options)}` }, (body === undefined ? {} : { "Content-Type": "application/json" })) }, (body === undefined ? {} : { body: JSON.stringify(body) })));
+        const text = yield response.text();
+        let parsed;
+        try {
+            parsed = text.length === 0 ? {} : JSON.parse(text);
+        }
+        catch (_a) {
+            throw new Error(`cursorHostedFiles ${url} returned non-JSON (${response.status})`);
+        }
+        if (!response.ok) {
+            throw new StoreApiError(response.status, `cursorHostedFiles ${url}: ${describeError(parsed, response.status)}`);
+        }
+        return parsed;
+    });
+}
+/**
+ * A non-2xx answer from the files API, carrying the status so a caller can
+ * tell "absent" apart from a failure it must not swallow.
+ */
+class StoreApiError extends Error {
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = "StoreApiError";
+    }
+}
+function describeError(parsed, status) {
+    if (parsed !== null &&
+        typeof parsed === "object" &&
+        "error" in parsed &&
+        typeof parsed.error === "string") {
+        return parsed.error;
+    }
+    if (parsed !== null &&
+        typeof parsed === "object" &&
+        "message" in parsed &&
+        typeof parsed.message === "string") {
+        return parsed.message;
+    }
+    return `HTTP ${status}`;
+}
+/** S3 returns quoted etags; the store compares them unquoted. */
+function normalizeEtag(raw) {
+    if (raw === null) {
+        return undefined;
+    }
+    const trimmed = raw.trim().replace(/^"+|"+$/g, "");
+    return trimmed === "" ? undefined : trimmed;
+}