@cursor/july 0.1.29 → 0.1.31

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

@@ -0,0 +1,540 @@
+/**
+ * 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.
+ *
+ * Everything goes through the public API under `/v0/agent-serve-files`, the same
+ * surface any API-key holder gets. This process is an ordinary client of it —
+ * there is no private endpoint, no second base URL, and nothing here that only
+ * works because the caller happens to be an Agent Serve engine. That matters
+ * beyond tidiness: a self-hosted deployment, a CI job, or a customer script can
+ * drive the same store with the same requests.
+ *
+ * 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());
+    });
+};
+import { createHash } from "node:crypto";
+import { FileConflictError, } from "../files.js";
+import { createAgentStorePresignedUrlValidatorForBackend } from "./agent-store-presigned-url.js";
+/**
+ * Same default as the hosted storage backend, inlined so this entrypoint does
+ * not import CLI code.
+ */
+const DEFAULT_CURSOR_EXTERNAL_API_URL = "https://api.cursor.com";
+const AGENT_SERVE_FILES_PATH = "/v0/agent-serve-files";
+/**
+ * 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";
+/** 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;
+/** 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) {
+    var _a;
+    const sourceId = (_a = env[AGENT_SERVE_STORE_SOURCE_ID_ENV_VAR]) === null || _a === void 0 ? void 0 : _a.trim();
+    return sourceId !== undefined && sourceId !== "";
+}
+/**
+ * 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 comes from the
+     * environment and the server maps it to a store on every request. Resolved
+     * per call rather than once at construction so a misconfigured environment
+     * fails where the operation is, not where the sink was created.
+     */
+    function withFiles(call) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const sourceId = resolveStoreSourceId(options);
+            return yield call({
+                path: (suffix = "") => `/${encodeURIComponent(sourceId)}${suffix}`,
+            });
+        });
+    }
+    /** One page of the paginated per-directory listing. */
+    function directoryPage(files, directory, pageToken) {
+        return __awaiter(this, void 0, void 0, function* () {
+            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()}`));
+        });
+    }
+    function listEntries(prefix) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return yield withFiles((files) => __awaiter(this, void 0, void 0, function* () {
+                var _a;
+                const raw = yield storeGet(options, files.path());
+                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));
+                    }
+                    return out;
+                }
+                // 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;
+            }));
+        });
+    }
+    /**
+     * Precondition for an unconditional write: replace what is there now, or
+     * create when nothing is.
+     */
+    function currentPrecondition(key) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const cached = observedEtags.get(key);
+            if (cached !== undefined) {
+                return { etag: cached };
+            }
+            const found = yield statKey(key);
+            // Unknown falls through to create-only. If the object does in fact exist,
+            // the store answers 412 and the caller gets a FileConflictError it can
+            // retry with an explicit `ifMatch` — degraded, but never wrong.
+            return (found === null || found === void 0 ? void 0 : found.etag) === undefined ? { new: true } : { etag: found.etag };
+        });
+    }
+    return {
+        // No local copy: bytes live in the store, so `materializedPath()` is
+        // `undefined` and the harness reaches files through `host.files`.
+        capabilities: { etags: true },
+        put(key, body, putOptions) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const sha = createHash("sha256").update(body).digest("hex");
+                const requested = putOptions === null || putOptions === void 0 ? void 0 : putOptions.ifMatch;
+                // The store rejects unconditional writes, so every put carries a
+                // precondition. `null` is create-only and an explicit etag is a caller
+                // assertion; an unconditional write has to learn the current state,
+                // because assuming "absent" would make replace fail on any process that
+                // has not already read the path — which is every fresh pod.
+                const precondition = requested === null
+                    ? { new: true }
+                    : requested !== undefined
+                        ? { etag: requested }
+                        : yield currentPrecondition(key);
+                return yield withFiles((files) => __awaiter(this, void 0, void 0, function* () {
+                    var _a;
+                    var _b;
+                    const presigned = yield storePost(options, files.path("/upload"), {
+                        files: [Object.assign({ path: key, sha, size: body.byteLength }, precondition)],
+                    });
+                    const instruction = (_a = presigned.files) === null || _a === void 0 ? void 0 : _a[0];
+                    if ((instruction === null || instruction === void 0 ? void 0 : instruction.url) === undefined) {
+                        // Files past the single-part threshold come back with a multipart
+                        // plan instead of a url; this backend does not implement multipart.
+                        throw new Error(`cursorHostedFiles: no single-part upload url for "${key}" (too large?)`);
+                    }
+                    const response = yield fetchImpl(options)(assertPresignedUrlSafe(options, instruction.url), {
+                        method: "PUT",
+                        headers: (_b = instruction.headers) !== null && _b !== void 0 ? _b : {},
+                        // A view over bytes is a valid fetch body; the DOM lib types are
+                        // narrower than the runtime, and copying into a Blob would double
+                        // the memory for every upload.
+                        body: body,
+                        // A redirect would re-send the body somewhere the presign did not
+                        // authorize.
+                        redirect: "manual",
+                    });
+                    if (response.status === 412) {
+                        // Someone else wrote between our etag observation and this PUT.
+                        observedEtags.delete(key);
+                        throw new FileConflictError(key, Object.assign({}, ("etag" in precondition
+                            ? { storedEtag: precondition.etag }
+                            : {})));
+                    }
+                    if (!response.ok) {
+                        throw new Error(`cursorHostedFiles: upload of "${key}" failed (HTTP ${response.status})`);
+                    }
+                    const etag = normalizeEtag(response.headers.get("etag"));
+                    if (etag !== undefined) {
+                        rememberEtag(key, etag);
+                    }
+                    return etag === undefined ? {} : { etag };
+                }));
+            });
+        },
+        get(key) {
+            return __awaiter(this, void 0, void 0, function* () {
+                return yield withFiles((files) => __awaiter(this, void 0, void 0, function* () {
+                    var _a, _b;
+                    const presigned = yield storePost(options, files.path("/download"), { paths: [key] });
+                    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;
+                    }
+                    const response = yield fetchImpl(options)(assertPresignedUrlSafe(options, url), {
+                        method: "GET",
+                        redirect: "manual",
+                    });
+                    if (response.status === 404 || response.status === 403) {
+                        // A presigned GET for a missing object surfaces as 403 on S3.
+                        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 }));
+                }));
+            });
+        },
+        delete(key) {
+            return __awaiter(this, void 0, void 0, function* () {
+                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, _b;
+                    const raw = yield storePost(options, files.path("/delete"), { files: [{ path: key, etag }] });
+                    // The API answers 200 with a per-file status, so a lost race would look
+                    // like success unless the outcome is read.
+                    const outcome = ((_a = raw.files) !== null && _a !== void 0 ? _a : []).find((entry) => entry.path === key);
+                    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);
+            });
+        },
+        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.
+ */
+function assertPresignedUrlSafe(options, raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch (_a) {
+        throw new Error("cursorHostedFiles: presigned URL is not a valid URL");
+    }
+    try {
+        createAgentStorePresignedUrlValidatorForBackend(resolveBaseUrl(options))(url);
+    }
+    catch (error) {
+        throw new Error(`cursorHostedFiles: refused presigned URL: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return url.toString();
+}
+function fetchImpl(options) {
+    var _a;
+    const impl = (_a = options.fetch) !== null && _a !== void 0 ? _a : globalThis.fetch;
+    if (typeof impl !== "function") {
+        throw new Error("cursorHostedFiles requires fetch");
+    }
+    return impl;
+}
+/**
+ * The file store this engine's deployment owns. Every request names it, so
+ * the server resolves the store row and this process never handles a store id.
+ *
+ * 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;
+    var _b;
+    const id = (_a = ((_b = options.storeSourceId) !== null && _b !== void 0 ? _b : process.env[AGENT_SERVE_STORE_SOURCE_ID_ENV_VAR])) === null || _a === void 0 ? void 0 : _a.trim();
+    if (id === undefined || id === "") {
+        throw new Error(`cursorHostedFiles requires ${AGENT_SERVE_STORE_SOURCE_ID_ENV_VAR} (set on Cursor-managed deployments)`);
+    }
+    return id;
+}
+function resolveApiKey(options) {
+    var _a;
+    var _b;
+    const key = (_a = ((_b = options.apiKey) !== null && _b !== void 0 ? _b : process.env.CURSOR_API_KEY)) === null || _a === void 0 ? void 0 : _a.trim();
+    if (key === undefined || key === "") {
+        throw new Error("cursorHostedFiles requires CURSOR_API_KEY (deployment pod credential on Cursor hosting)");
+    }
+    return key;
+}
+function resolveBaseUrl(options) {
+    var _a, _b;
+    return trimTrailingSlash((_b = (_a = options.baseUrl) !== null && _a !== void 0 ? _a : process.env.CURSOR_API_BASE_URL) !== null && _b !== void 0 ? _b : DEFAULT_CURSOR_EXTERNAL_API_URL);
+}
+function trimTrailingSlash(raw) {
+    const trimmed = raw.trim();
+    return trimmed.endsWith("/") ? trimmed.slice(0, -1) : trimmed;
+}
+/**
+ * Public agent-serve-files API call. The pod credential is the whole authorization:
+ * the API forwards this caller's identity to the store service, which checks it
+ * 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, `${resolveBaseUrl(options)}${AGENT_SERVE_FILES_PATH}${path}`, body);
+    });
+}
+function storeGet(options, path) {
+    return __awaiter(this, void 0, void 0, function* () {
+        return yield sendJson(options, `${resolveBaseUrl(options)}${AGENT_SERVE_FILES_PATH}${path}`, "GET");
+    });
+}
+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 fetchImpl(options)(url, Object.assign({ method, headers: Object.assign({ Authorization: `Bearer ${resolveApiKey(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 Error(`cursorHostedFiles ${url}: ${describeError(parsed, response.status)}`);
+        }
+        return parsed;
+    });
+}
+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;
+}

package/dist/files-backends/local-fs.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Local-disk file sink: one file per key under a directory you own.
+ *
+ * The default off Cursor-managed hosting. Paths are real, so the harness can
+ * open a file with its ordinary tools — that is why this reports
+ * `materialized` — and there are no etags, so `conflictDetection` is honestly
+ * false and concurrent writers are last-writer-wins.
+ */
+import { type FileSink } from "../files.js";
+export interface LocalFilesOptions {
+    /** Directory the sink owns. */
+    filesRoot: string;
+    /**
+     * Prefix trimmed off each key before building the on-disk path, so the tree
+     * reads `deployment/notes.md` instead of repeating the framework key root.
+     *
+     * Framework-supplied. Authors should omit it: the value has to match the
+     * internal key scheme exactly, and a near-miss would silently nest files
+     * under a redundant path instead of failing. Omitted, keys are stored
+     * verbatim, which is always correct and lets two agents share one root.
+     */
+    stripKeyPrefix?: string;
+}
+/**
+ * Default sink: one file per key under the state root, written atomically.
+ *
+ * Reports `materialized` because the paths are real — that is what lets the
+ * harness read a file with its ordinary tools — and reports no `etags`, so
+ * `host.files.capabilities.conflictDetection` is honestly false and concurrent
+ * writers are last-writer-wins.
+ */
+export declare function localFiles(options: LocalFilesOptions): FileSink;
+//# sourceMappingURL=local-fs.d.ts.map

package/dist/files-backends/local-fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-fs.d.ts","sourceRoot":"","sources":["../../src/files-backends/local-fs.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAaH,OAAO,EAEL,KAAK,QAAQ,EAGd,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,iBAAiB;IAChC,+BAA+B;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,QAAQ,CAmG/D"}