@cursor/bdk 0.2.2 → 0.2.4

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

@@ -1,1212 +0,0 @@
-/**
- * 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.
- */
-
-import { createHash } from "node:crypto";
-import {
-  FileConflictError,
-  type FileSink,
-  type FileSinkBody,
-  type FileSinkEntry,
-  type FileSinkPutResult,
-} from "../files.js";
-import { mapBounded } from "../internal/bounded.js";
-import {
-  type CursorApiTransportOptions,
-  resolveCursorApiBaseUrl,
-  resolveCursorApiFetch,
-  resolveCursorApiKey,
-} from "../internal/cursor/cursor-api-transport.js";
-import {
-  resolveDeploymentStoreSourceIdSync,
-  resolveFrameworkStoreSourceIdSync,
-  resolveStoreProtocolSync,
-  storeProtocolEnablesFactoryFlush,
-} from "../internal/cursor/hosted-store-secrets.js";
-import { createAgentStorePresignedUrlValidatorForBackend } from "./agent-store-presigned-url.js";
-
-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 = 1_000;
-
-/** Bounded directory page for point lookups. */
-const DIRECTORY_PAGE_SIZE = 1_000;
-/**
- * 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 = 1_000;
-
-/**
- * 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: NodeJS.ProcessEnv = process.env): boolean {
-  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: NodeJS.ProcessEnv = process.env): boolean {
-  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 = env.CURSOR_API_KEY?.trim();
-  return key !== undefined && key !== "";
-}
-
-/**
- * Base URL / credential / fetch resolution is the shared
- * {@link CursorApiTransportOptions} (`internal/cursor/cursor-api-transport.ts`),
- * so this sink and the domain-lane store API client resolve identically.
- */
-export interface CursorHostedFilesOptions extends CursorApiTransportOptions {
-  /** File store to address (default: `AGENT_SERVE_STORE_SOURCE_ID`). */
-  storeSourceId?: string;
-  /**
-   * Lazy store source id, re-resolved on every call and preferred over
-   * {@link storeSourceId} — freeze bind drops ids into `/run/cursor/secrets`
-   * after serve start without restarting July.
-   */
-  resolveStoreSourceId?: () => string | undefined;
-  /**
-   * Lazy store protocol pin (default: env, then the task-bound file). When it
-   * enables the factory flush wire (`factory-flush-v1`, or the superset
-   * domain-API pin `factory-api-v1`) and the source id maps to a deployment
-   * store role, requests ride the factory store API instead of
-   * `/v0/agent-serve-files`. Any other value keeps `/v0`.
-   */
-  resolveStoreProtocol?: () => string | undefined;
-}
-
-/**
- * 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
- * versioned public API, and a client that hard-required every field would break
- * on an additive change it could otherwise ignore.
- */
-interface ApiFile {
-  path?: string;
-  sizeBytes?: number;
-  etag?: string;
-  updatedAt?: string;
-}
-
-interface ApiFileListing {
-  files?: ApiFile[];
-  complete?: boolean;
-  /** Immediate subdirectories; only returned by the `?path=` form. */
-  directories?: string[];
-  nextPageToken?: string;
-}
-
-interface ApiPresignResponse {
-  files?: Array<{
-    path?: string;
-    url?: string;
-    headers?: Record<string, string>;
-  }>;
-}
-
-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" | "getMany"> & {
-  /** Narrower than {@link FileSink.get}: this backend always reports the etag. */
-  get(key: string): Promise<FileSinkBody | undefined>;
-  /** Always present here (and narrowed like {@link get}); optional on {@link FileSink}. */
-  getMany(keys: readonly string[]): Promise<Array<FileSinkBody | undefined>>;
-};
-
-/**
- * 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: CursorHostedFilesOptions = {}): HostedFilesMethods {
-  /**
-   * 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<string, string>();
-  const rememberEtag = (key: string, etag: string): void => {
-    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.
-   */
-  async function withFiles<T>(call: (files: FilesTarget) => Promise<T>): Promise<T> {
-    const sourceId = resolveStoreSourceId(options);
-    const protocol = options.resolveStoreProtocol?.() ?? 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 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}`,
-    });
-  }
-
-  /**
-   * 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.
-   */
-  async function downloadPresigned(key: string, url: string): Promise<FileSinkBody | undefined> {
-    const response = await 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 {
-      body: new Uint8Array(await response.arrayBuffer()),
-      ...(etag === undefined ? {} : { etag }),
-    };
-  }
-
-  /** One page of the paginated per-directory listing. */
-  async function directoryPage(
-    files: FilesTarget,
-    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),
-    });
-    if (pageToken !== undefined) {
-      query.set("pageToken", pageToken);
-    }
-    return await storeGet<ApiFileListing>(options, files.path(`?${query.toString()}`));
-  }
-
-  /** 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 unscopedListing(files);
-      if (raw.complete === true) {
-        const out: FileSinkEntry[] = [];
-        for (const file of raw.files ?? []) {
-          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 await 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.
-   */
-  async function walkDirectoryTree(files: FilesTarget, prefix: string): Promise<FileSinkEntry[]> {
-    const slash = prefix.lastIndexOf("/");
-    const pending: string[] = [slash === -1 ? "" : prefix.slice(0, slash)];
-    const queued = new Set<string>(pending);
-    const out: FileSinkEntry[] = [];
-    let pageBudget = MAX_LIST_WALK_PAGES;
-    while (pending.length > 0) {
-      const directory = pending.pop() as string;
-      let pageToken: string | undefined;
-      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 = await directoryPage(files, directory, pageToken);
-        for (const file of page.files ?? []) {
-          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 page.directories ?? []) {
-          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: ApiFile, key: string): FileSinkEntry {
-    if (typeof file.etag === "string" && file.etag !== "") {
-      rememberEtag(key, file.etag);
-    }
-    const mtimeMs = typeof file.updatedAt === "string" ? Date.parse(file.updatedAt) : undefined;
-    return {
-      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.
-   */
-  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 => {
-      let pageToken: string | undefined;
-      for (let page = 0; page < MAX_DIRECTORY_PAGES; page += 1) {
-        const raw = await directoryPage(files, directory, pageToken);
-        for (const file of raw.files ?? []) {
-          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;
-    });
-  }
-
-  /** 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 resolveCursorApiFetch(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 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: { 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 {
-        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 },
-
-    async put(key, body, putOptions): Promise<FileSinkPutResult> {
-      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`);
-        }
-        return await settlePut(
-          files,
-          {
-            ...entry,
-            cachedEtagUsed: resolved.cachedEtagUsed,
-            staleEtag: resolved.staleEtag,
-          },
-          first,
-        );
-      });
-    },
-
-    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,
-          }));
-        }
-        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 => {
-        // 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: ApiPresignResponse;
-        try {
-          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;
-          }
-          throw error;
-        }
-        const url = presigned.files?.[0]?.url;
-        if (url === undefined) {
-          return undefined;
-        }
-        return await downloadPresigned(key, url);
-      });
-    },
-
-    async getMany(keys): Promise<Array<FileSinkBody | undefined>> {
-      if (keys.length === 0) {
-        return [];
-      }
-      const bodies = await withFiles(async files => {
-        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 await mapBounded([...keys], GET_MANY_DOWNLOAD_CONCURRENCY, async key => {
-            const presigned = await storePost<ApiPresignResponse>(
-              options,
-              files.path("/download"),
-              { paths: [key] },
-            ).catch((error: unknown) => {
-              if (error instanceof StoreApiError && error.status === 404) {
-                return undefined;
-              }
-              throw error;
-            });
-            const url = presigned?.files?.[0]?.url;
-            if (url === undefined) {
-              return undefined;
-            }
-            return await downloadPresigned(key, url);
-          });
-        }
-        const urls = new Map<string, string>();
-        for (let from = 0; from < keys.length; from += READ_PRESIGN_BATCH_MAX) {
-          const chunk = keys.slice(from, from + READ_PRESIGN_BATCH_MAX);
-          let presigned: ApiPresignResponse;
-          try {
-            presigned = await flushPost<ApiPresignResponse>(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 presigned.files ?? []) {
-            if (entry.path !== undefined && entry.url !== undefined) {
-              urls.set(entry.path, entry.url);
-            }
-          }
-        }
-        return await mapBounded([...keys], GET_MANY_DOWNLOAD_CONCURRENCY, async key => {
-          const url = urls.get(key);
-          if (url !== undefined) {
-            return await 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 = await flushPost<ApiPresignResponse>(options, "/read", {
-            store: files.store,
-            paths: [key],
-          }).catch((error: unknown) => {
-            // 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 = presigned?.files?.[0]?.url;
-          if (singleUrl === undefined) {
-            return undefined;
-          }
-          return await downloadPresigned(key, singleUrl);
-        });
-      });
-      return bodies;
-    },
-
-    async delete(key): Promise<void> {
-      const handled = await withFiles(async files => {
-        if (files.wire !== "flush") {
-          return false;
-        }
-        // With an observed etag the flush delete is If-Match on that version.
-        // Without one, the server tombstones whatever live object occupies
-        // the key (no directory walk here) and an absent key 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.
-        const found = await statKey(key);
-        if (found?.etag === undefined) {
-          return;
-        }
-      }
-      const etag = observedEtags.get(key);
-      if (etag === undefined) {
-        return;
-      }
-      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"), {
-          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 = (raw.files ?? []).find(entry => entry.path === key);
-        if (outcome?.status === "conflict") {
-          observedEtags.delete(key);
-          throw new FileConflictError(key, {
-            ...(outcome.etag === undefined
-              ? {}
-              : { storedEtag: normalizeEtag(outcome.etag) ?? outcome.etag }),
-          });
-        }
-      });
-      observedEtags.delete(key);
-    },
-
-    list: listEntries,
-
-    async stat(key): Promise<FileSinkEntry | undefined> {
-      return await 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: CursorHostedFilesOptions, raw: string): string {
-  let url: URL;
-  try {
-    url = new URL(raw);
-  } 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(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: CursorHostedFilesOptions): string {
-  const id = (
-    options.resolveStoreSourceId?.() ??
-    options.storeSourceId ??
-    resolveDeploymentStoreSourceIdSync(process.env)
-  )?.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: ReadonlySet<string> = new Set(
-  (process.env.CURSOR_HOSTED_FILES_DEV_PRESIGN_HOSTS ?? "")
-    .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.
- */
-async function storePost<T>(
-  options: CursorHostedFilesOptions,
-  path: string,
-  body: Record<string, unknown>,
-): Promise<T> {
-  return await postJson<T>(
-    options,
-    `${resolveCursorApiBaseUrl(options)}${AGENT_SERVE_FILES_PATH}${path}`,
-    body,
-  );
-}
-
-async function storeGet<T>(options: CursorHostedFilesOptions, path: string): Promise<T> {
-  return await sendJson<T>(
-    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`).
- */
-async function flushPost<T>(
-  options: CursorHostedFilesOptions,
-  path: string,
-  body: Record<string, unknown>,
-): Promise<T> {
-  return await postJson<T>(
-    options,
-    `${resolveCursorApiBaseUrl(options)}${AGENTSDK_STORE_PATH}${path}`,
-    body,
-  );
-}
-
-async function postJson<T>(
-  options: CursorHostedFilesOptions,
-  url: string,
-  body: Record<string, unknown>,
-): Promise<T> {
-  return await sendJson<T>(options, url, "POST", body);
-}
-
-async function sendJson<T>(
-  options: CursorHostedFilesOptions,
-  url: string,
-  method: "GET" | "POST",
-  body?: Record<string, unknown>,
-): Promise<T> {
-  const response = await resolveCursorApiFetch(options)(url, {
-    method,
-    headers: {
-      Authorization: `Bearer ${resolveCursorApiKey(options)}`,
-      ...(body === undefined ? {} : { "Content-Type": "application/json" }),
-    },
-    ...(body === undefined ? {} : { body: JSON.stringify(body) }),
-  });
-  const text = await response.text();
-  let parsed: unknown;
-  try {
-    parsed = text.length === 0 ? {} : JSON.parse(text);
-  } catch {
-    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 as T;
-}
-
-/**
- * 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(
-    readonly status: number,
-    message: string,
-  ) {
-    super(message);
-    this.name = "StoreApiError";
-  }
-}
-
-function describeError(parsed: unknown, status: number): string {
-  if (
-    parsed !== null &&
-    typeof parsed === "object" &&
-    "error" in parsed &&
-    typeof (parsed as { error: unknown }).error === "string"
-  ) {
-    return (parsed as { error: string }).error;
-  }
-  if (
-    parsed !== null &&
-    typeof parsed === "object" &&
-    "message" in parsed &&
-    typeof (parsed as { message: unknown }).message === "string"
-  ) {
-    return (parsed as { message: string }).message;
-  }
-  return `HTTP ${status}`;
-}
-
-/** S3 returns quoted etags; the store compares them unquoted. */
-function normalizeEtag(raw: string | null): string | undefined {
-  if (raw === null) {
-    return undefined;
-  }
-  const trimmed = raw.trim().replace(/^"+|"+$/g, "");
-  return trimmed === "" ? undefined : trimmed;
-}