@cursor/bdk 0.2.1

package/dist/internal/framework-file-storage.js

@@ -0,0 +1,338 @@
+/**
+ * Framework-level file storage for v2 hosted engines.
+ *
+ * Hosted deployments carry two file stores with different audiences:
+ *
+ * - the **user-level** store (`AGENT_SERVE_STORE_SOURCE_ID`) holds
+ *   author-facing bytes — `ctx.host.files`, skills, memory, artifacts — and
+ *   is browsable from the dashboard and mountable on cloud-runtime VMs;
+ * - the **framework-level** store (`AGENT_SERVE_FRAMEWORK_STORE_SOURCE_ID`)
+ *   holds engine-owned session state — session records, event transcripts,
+ *   hosted-execution run logs, the continuation index, and the SDK
+ *   conversation mirror — and is never mounted into author code or models.
+ *   The authenticated dashboard may read diagnostic families, but never the
+ *   continuation index.
+ *
+ * This module puts framework session state on the framework store. The
+ * {@link storageKeys} scheme was designed for exactly this: keys are a
+ * stable versioned contract that sinks may route on, so
+ * {@link composeFrameworkStorage} splits one {@link StorageConfig} by key
+ * kind — `session` / `session-events` / `session-runs` / `logs` /
+ * `continuation` go to the framework file store (file-shaped; the store
+ * accepts values up to 64 MiB per
+ * object without chunking, versus the KV proxy's 1 MiB row cap), while
+ * author `kv`, eval runs, and conditional writes stay on the control-plane
+ * KV proxy (the dashboard reads them there, and CAS needs a database).
+ *
+ * v2 only, by construction: the composite is selected in
+ * framework-storage-selection.ts, which v1 never reaches with a
+ * platform-selected definition.
+ */
+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 { AGENTSDK_STORAGE_KEY_ROOT } from "../storage-protocol.js";
+import { mapBounded } from "./bounded.js";
+/**
+ * Key kinds (`agentsdk/v1/{agent}/{kind}/…`) that live on the framework
+ * file store. Everything else stays on the KV sink.
+ */
+const FRAMEWORK_FILE_KINDS = new Set([
+    "session",
+    "session-events",
+    "session-runs",
+    "logs",
+    "continuation",
+]);
+/**
+ * Whether a framework-minted key (or list prefix) belongs on the framework
+ * file store. Prefixes used by the coordinator are always at least
+ * kind-scoped (`…/{agent}/session/`), so a prefix routes wholly to one side.
+ */
+export function isFrameworkFileKey(key) {
+    if (!key.startsWith(`${AGENTSDK_STORAGE_KEY_ROOT}/`)) {
+        return false;
+    }
+    const rest = key.slice(AGENTSDK_STORAGE_KEY_ROOT.length + 1);
+    const agentEnd = rest.indexOf("/");
+    if (agentEnd === -1) {
+        return false;
+    }
+    const afterAgent = rest.slice(agentEnd + 1);
+    const kindEnd = afterAgent.indexOf("/");
+    const kind = kindEnd === -1 ? afterAgent : afterAgent.slice(0, kindEnd);
+    return FRAMEWORK_FILE_KINDS.has(kind);
+}
+/** Parallel per-key reads backing `list` (each is presign + object GET). */
+const LIST_READ_CONCURRENCY = 8;
+/**
+ * A storage key whose path the file store cannot represent (an empty, `.`,
+ * or `..` segment — possible only through caller-controlled segments such
+ * as continuation tokens or a caller-supplied session id). Such an object
+ * can never exist in the store, so reads are a definitive miss rather than
+ * a per-request 400 that the lazy-restore path would propagate forever.
+ */
+function isUnrepresentableFileKey(key) {
+    return key.split("/").some(segment => segment === "" || segment === "." || segment === "..");
+}
+/**
+ * Adapt a {@link FileSink} to the `defineStorage` KV core. Storage keys are
+ * framework-minted (URI-encoded, length-bounded segments — see
+ * {@link storageKeys}), so they are used as file keys verbatim; values are
+ * stored as JSON bytes. Parse failures throw: on the lazy-restore path a
+ * corrupt document must fail the follow-up rather than read as a miss, and
+ * the startup bulk restore already logs-and-skips a throwing `list`.
+ */
+export function fileSinkStorageCore(sink) {
+    return {
+        put(key, value) {
+            return __awaiter(this, void 0, void 0, function* () {
+                if (isUnrepresentableFileKey(key)) {
+                    // Loud rather than silent: the coordinator logs and drops failed
+                    // mirror writes (at-most-once), and awaited callers must not
+                    // believe an impossible write landed.
+                    throw new Error(`framework file storage: key "${key}" has a path segment the store cannot represent`);
+                }
+                yield sink.put(key, encodeDocument(key, value));
+            });
+        },
+        putMany(entries) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const results = entries.map(entry => ({
+                    key: entry.key,
+                }));
+                const writable = [];
+                for (let index = 0; index < entries.length; index += 1) {
+                    const entry = entries[index];
+                    if (entry === undefined) {
+                        continue;
+                    }
+                    if (isUnrepresentableFileKey(entry.key)) {
+                        results[index] = {
+                            key: entry.key,
+                            error: new Error(`framework file storage: key "${entry.key}" has a path segment the store cannot represent`),
+                        };
+                        continue;
+                    }
+                    writable.push({
+                        index,
+                        key: entry.key,
+                        body: encodeDocument(entry.key, entry.value),
+                    });
+                }
+                if (writable.length === 0) {
+                    return results;
+                }
+                if (sink.putMany !== undefined) {
+                    // The point of the batch: one backend round trip for the flush.
+                    const settled = yield sink.putMany(writable.map(({ key, body }) => ({ key, body })));
+                    for (let i = 0; i < writable.length; i += 1) {
+                        const target = writable[i];
+                        const outcome = settled[i];
+                        if (target === undefined) {
+                            continue;
+                        }
+                        if ((outcome === null || outcome === void 0 ? void 0 : outcome.status) === "rejected") {
+                            results[target.index] = { key: target.key, error: outcome.reason };
+                        }
+                    }
+                    return results;
+                }
+                // No batch support: sequential puts, preserving the sink's strict
+                // one-at-a-time ordering contract.
+                for (const target of writable) {
+                    try {
+                        yield sink.put(target.key, target.body);
+                    }
+                    catch (error) {
+                        results[target.index] = { key: target.key, error };
+                    }
+                }
+                return results;
+            });
+        },
+        get(key) {
+            return __awaiter(this, void 0, void 0, function* () {
+                if (isUnrepresentableFileKey(key)) {
+                    return undefined;
+                }
+                const body = yield sink.get(key);
+                if (body === undefined) {
+                    return undefined;
+                }
+                return decodeDocument(key, body instanceof Uint8Array ? body : body.body);
+            });
+        },
+        delete(key) {
+            return __awaiter(this, void 0, void 0, function* () {
+                if (isUnrepresentableFileKey(key)) {
+                    return;
+                }
+                yield sink.delete(key);
+            });
+        },
+        list(prefix) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const entries = yield sink.list(prefix);
+                // FileSink.list returns metadata only, so the values are their own
+                // reads. Prefer the sink's batched read — on the hosted sink that is
+                // one control-plane call per 100 keys instead of one per key, which is
+                // what keeps a big restore under the store's per-deployment rate
+                // budget — and fall back to bounded per-key gets elsewhere.
+                const bodies = sink.getMany !== undefined
+                    ? yield sink.getMany(entries.map(entry => entry.key))
+                    : yield mapBounded(entries, LIST_READ_CONCURRENCY, entry => sink.get(entry.key));
+                const out = [];
+                for (let index = 0; index < entries.length; index += 1) {
+                    const entry = entries[index];
+                    const body = bodies[index];
+                    if (entry === undefined || body === undefined) {
+                        // Deleted between list and read; a miss is not corruption.
+                        continue;
+                    }
+                    out.push({
+                        key: entry.key,
+                        value: decodeDocument(entry.key, body instanceof Uint8Array ? body : body.body),
+                    });
+                }
+                return out;
+            });
+        },
+    };
+}
+function frameworkFileKind(key) {
+    if (!key.startsWith(`${AGENTSDK_STORAGE_KEY_ROOT}/`)) {
+        return undefined;
+    }
+    const rest = key.slice(AGENTSDK_STORAGE_KEY_ROOT.length + 1);
+    const agentEnd = rest.indexOf("/");
+    if (agentEnd === -1) {
+        return undefined;
+    }
+    const afterAgent = rest.slice(agentEnd + 1);
+    const kindEnd = afterAgent.indexOf("/");
+    return kindEnd === -1 ? afterAgent : afterAgent.slice(0, kindEnd);
+}
+function isLogKey(key) {
+    return frameworkFileKind(key) === "logs";
+}
+function encodeDocument(key, value) {
+    // start.log is raw UTF-8, not a JSON document. Stringify would quote
+    // every line and store a JSON string literal instead of the tee.
+    if (isLogKey(key)) {
+        return new TextEncoder().encode(typeof value === "string" ? value : JSON.stringify(value));
+    }
+    return new TextEncoder().encode(JSON.stringify(value));
+}
+function decodeDocument(key, bytes) {
+    const text = new TextDecoder().decode(bytes);
+    if (isLogKey(key)) {
+        return text;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch (error) {
+        throw new Error(`framework file storage: stored document at "${key}" is not JSON (${error instanceof Error ? error.message : String(error)})`);
+    }
+}
+/**
+ * Split one storage core by key kind: framework session state to `files`,
+ * everything else to `kv`. Spread over the KV backend when building the
+ * full definition so its `evals` group (and the cursor-hosted marker)
+ * rides along untouched; wrap the KV `cas` group with
+ * {@link frameworkGuardedCas} rather than spreading it as-is.
+ */
+export function composeFrameworkStorage(input) {
+    const route = (key) => isFrameworkFileKey(key) ? input.files : input.kv;
+    return {
+        put: (key, value, ctx) => route(key).put(key, value, ctx),
+        putMany(entries, ctx) {
+            return __awaiter(this, void 0, void 0, function* () {
+                // Partition by destination store, batch each side, and reassemble
+                // per-entry outcomes in input order.
+                const indexed = entries.map((entry, index) => ({ entry, index }));
+                const results = entries.map(entry => ({
+                    key: entry.key,
+                }));
+                for (const core of [input.files, input.kv]) {
+                    const side = indexed.filter(({ entry }) => route(entry.key) === core);
+                    if (side.length === 0) {
+                        continue;
+                    }
+                    if (core.putMany === undefined) {
+                        // No batch write on this side (the KV proxy): sequential puts,
+                        // preserving the strict one-at-a-time ordering it promises.
+                        for (const { entry, index } of side) {
+                            try {
+                                yield core.put(entry.key, entry.value, ctx);
+                            }
+                            catch (error) {
+                                results[index] = { key: entry.key, error };
+                            }
+                        }
+                        continue;
+                    }
+                    const settled = yield core.putMany(side.map(({ entry }) => entry), ctx);
+                    for (let i = 0; i < side.length; i += 1) {
+                        const target = side[i];
+                        const outcome = settled[i];
+                        if (target !== undefined && outcome !== undefined) {
+                            results[target.index] = outcome;
+                        }
+                    }
+                }
+                return results;
+            });
+        },
+        get: (key, ctx) => route(key).get(key, ctx),
+        delete: (key, ctx) => route(key).delete(key, ctx),
+        list: (prefix, ctx) => route(prefix).list(prefix, ctx),
+        // Session records — the only `listNewest` consumer — are framework file
+        // keys, and the file store has no write-time ordering. Spreading the KV
+        // backend's `listNewest` through would query rows that live elsewhere
+        // (stale KV leftovers, or nothing), so the composed core explicitly has
+        // none and the engine falls back to the routed `list`.
+        listNewest: undefined,
+    };
+}
+/**
+ * The KV backend's conditional writes, refusing framework-file keys.
+ *
+ * CAS runs on the KV proxy (a database row version); the plain core routes
+ * framework session state to the file store. A future coordination path
+ * that CASes a `session/` or `continuation/` key would otherwise read and
+ * write a different store than the plain path — silent split-brain. Fail
+ * loudly instead; nothing in the package CASes those kinds today.
+ */
+export function frameworkGuardedCas(cas) {
+    const refuse = (key) => {
+        if (isFrameworkFileKey(key)) {
+            throw new Error(`framework file storage: conditional writes are KV-only, but "${key}" routes to the framework file store`);
+        }
+    };
+    return {
+        getWithVersion: (key, ctx) => {
+            refuse(key);
+            return cas.getWithVersion(key, ctx);
+        },
+        putIfAbsent: (key, value, ctx) => {
+            refuse(key);
+            return cas.putIfAbsent(key, value, ctx);
+        },
+        putIfVersion: (key, value, expectedVersion, ctx) => {
+            refuse(key);
+            return cas.putIfVersion(key, value, expectedVersion, ctx);
+        },
+        listKeys: (prefix, ctx) => {
+            refuse(prefix);
+            return cas.listKeys(prefix, ctx);
+        },
+    };
+}

package/dist/internal/framework-storage-selection.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Which backend framework session state is mirrored to.
+ *
+ * Framework state — session records, event chunks, the continuation index —
+ * is how a session outlives the process that served it. On architecture v1
+ * that mirror exists only when the agent author wrote `agent/storage.ts`,
+ * which makes platform durability an agent-level decision: of the
+ * first-party agents, some choose `cursorHostedStorage()` and some choose
+ * `fileKv()` (pod-local disk, lost on pod replacement), and one selects
+ * between them at runtime by reading the deployment-id environment variable
+ * itself.
+ *
+ * That selection is a hosting-mode question, not an authoring question.
+ * Architecture v2 moves it here: `agent/storage.ts` is rejected at
+ * discovery (error diagnostic, so serve and deploy fail early), and the
+ * platform picks the default. Architecture v1 with no authored file now
+ * uses the same hosted-vs-self-hosted split, so deleting `agent/storage.ts`
+ * (required to deploy the same tree onto v2) does not drop the Cursor-hosted
+ * session mirror on a still-v1 pod.
+ *
+ * - **Cursor-managed hosting** (the deployment-generation environment
+ *   variable is set, same signal that registers `GET /v1/manifest`):
+ *   the deployment's **framework-level file store**
+ *   (`AGENT_SERVE_FRAMEWORK_STORE_SOURCE_ID`, bound at task time) holds
+ *   session records, event transcripts, and the continuation index —
+ *   file-shaped state on file storage, apart from the author-facing user
+ *   store. Author `host.kv`, eval runs, and conditional writes ride the
+ *   AgentSDK v2 KV proxy (cursor-hosted-v2.ts), which resolves the
+ *   pod service account to the factorydb deployment row (the v1 Bugbot
+ *   proxy cannot resolve v2 pods at all). Framework session state never
+ *   routes to the KV proxy — the composite splits by key kind — so
+ *   transcripts stay off the author-reachable KV namespace. The API key
+ *   resolves through the full credential chain on every call because hosted
+ *   freeze snapshots listen unsigned and the binder drops the key file
+ *   after restore.
+ * - **Self-hosted**: no mirror. `--state-root` is the durable copy, which
+ *   is correct when the operator owns the disk.
+ *
+ * v1 still honors an authored `agent/storage.ts` when present. Hosted v1
+ * pods with no authored file get the Cursor-hosted lazy mirror (gated on
+ * `AGENT_SERVE_DEPLOYMENT_ID`, the same signal the previous authored sinks
+ * used). Self-hosted v1 with no authored file stays disk-only.
+ *
+ * Local disk is not part of this decision. `<stateRoot>/sessions/<id>/`
+ * already holds `session.json` and `events.ndjson` unconditionally, through
+ * the session store; what this selects is the durable mirror *beyond* the
+ * pod's filesystem.
+ */
+import { type StorageDefinition } from "../storage.js";
+import type { AgentArchitecture } from "../types.js";
+export interface FrameworkStorageSelectionInput {
+    /** `agent/storage.ts`, when the author wrote one (v1 only: discovery rejects it on v2). */
+    readonly authored: StorageDefinition | undefined;
+    /** {@link AgentConfig.architecture}; discovery fills `"v2"` when omitted. */
+    readonly architecture?: AgentArchitecture | undefined;
+    /** Environment override for tests; defaults to `process.env`. */
+    readonly env?: Record<string, string | undefined>;
+}
+/**
+ * Pick the backend for framework session state.
+ *
+ * Returns `undefined` when there is no mirror, in which case the pod's local
+ * disk is the only copy.
+ */
+export declare function selectFrameworkStorageDefinition(input: FrameworkStorageSelectionInput): StorageDefinition | undefined;
+//# sourceMappingURL=framework-storage-selection.d.ts.map

package/dist/internal/framework-storage-selection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"framework-storage-selection.d.ts","sourceRoot":"","sources":["../../src/internal/framework-storage-selection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAGH,OAAO,EAAiB,KAAK,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAMtE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AASrD,MAAM,WAAW,8BAA8B;IAC7C,2FAA2F;IAC3F,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,GAAG,SAAS,CAAC;IACjD,6EAA6E;IAC7E,QAAQ,CAAC,YAAY,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAC;IACtD,iEAAiE;IACjE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;CACnD;AAED;;;;;GAKG;AACH,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,8BAA8B,GACpC,iBAAiB,GAAG,SAAS,CAyE/B"}

package/dist/internal/framework-storage-selection.js

@@ -0,0 +1,123 @@
+/**
+ * Which backend framework session state is mirrored to.
+ *
+ * Framework state — session records, event chunks, the continuation index —
+ * is how a session outlives the process that served it. On architecture v1
+ * that mirror exists only when the agent author wrote `agent/storage.ts`,
+ * which makes platform durability an agent-level decision: of the
+ * first-party agents, some choose `cursorHostedStorage()` and some choose
+ * `fileKv()` (pod-local disk, lost on pod replacement), and one selects
+ * between them at runtime by reading the deployment-id environment variable
+ * itself.
+ *
+ * That selection is a hosting-mode question, not an authoring question.
+ * Architecture v2 moves it here: `agent/storage.ts` is rejected at
+ * discovery (error diagnostic, so serve and deploy fail early), and the
+ * platform picks the default. Architecture v1 with no authored file now
+ * uses the same hosted-vs-self-hosted split, so deleting `agent/storage.ts`
+ * (required to deploy the same tree onto v2) does not drop the Cursor-hosted
+ * session mirror on a still-v1 pod.
+ *
+ * - **Cursor-managed hosting** (the deployment-generation environment
+ *   variable is set, same signal that registers `GET /v1/manifest`):
+ *   the deployment's **framework-level file store**
+ *   (`AGENT_SERVE_FRAMEWORK_STORE_SOURCE_ID`, bound at task time) holds
+ *   session records, event transcripts, and the continuation index —
+ *   file-shaped state on file storage, apart from the author-facing user
+ *   store. Author `host.kv`, eval runs, and conditional writes ride the
+ *   AgentSDK v2 KV proxy (cursor-hosted-v2.ts), which resolves the
+ *   pod service account to the factorydb deployment row (the v1 Bugbot
+ *   proxy cannot resolve v2 pods at all). Framework session state never
+ *   routes to the KV proxy — the composite splits by key kind — so
+ *   transcripts stay off the author-reachable KV namespace. The API key
+ *   resolves through the full credential chain on every call because hosted
+ *   freeze snapshots listen unsigned and the binder drops the key file
+ *   after restore.
+ * - **Self-hosted**: no mirror. `--state-root` is the durable copy, which
+ *   is correct when the operator owns the disk.
+ *
+ * v1 still honors an authored `agent/storage.ts` when present. Hosted v1
+ * pods with no authored file get the Cursor-hosted lazy mirror (gated on
+ * `AGENT_SERVE_DEPLOYMENT_ID`, the same signal the previous authored sinks
+ * used). Self-hosted v1 with no authored file stays disk-only.
+ *
+ * Local disk is not part of this decision. `<stateRoot>/sessions/<id>/`
+ * already holds `session.json` and `events.ndjson` unconditionally, through
+ * the session store; what this selects is the durable mirror *beyond* the
+ * pod's filesystem.
+ */
+import { cursorHostedFiles } from "../files-backends/cursor-hosted.js";
+import { defineStorage } from "../storage.js";
+import { AGENT_SERVE_DEPLOYMENT_ID_ENV_VAR, cursorHostedStorage, } from "../storage-backends/cursor-hosted.js";
+import { cursorHostedStorageV2 } from "../storage-backends/cursor-hosted-v2.js";
+import { resolveApiKeySync } from "./cursor/credentials.js";
+import { composeFrameworkStorage, fileSinkStorageCore, frameworkGuardedCas, } from "./framework-file-storage.js";
+import { resolveAgentV2Hosting } from "./v2-hosting.js";
+/**
+ * Pick the backend for framework session state.
+ *
+ * Returns `undefined` when there is no mirror, in which case the pod's local
+ * disk is the only copy.
+ */
+export function selectFrameworkStorageDefinition(input) {
+    var _a, _b;
+    if (input.architecture !== "v2") {
+        if (input.authored !== undefined) {
+            return input.authored;
+        }
+        const env = (_a = input.env) !== null && _a !== void 0 ? _a : process.env;
+        if (((_b = env[AGENT_SERVE_DEPLOYMENT_ID_ENV_VAR]) !== null && _b !== void 0 ? _b : "").trim() !== "") {
+            // Hosted v1 pod with no authored sink: keep the Cursor-hosted
+            // mirror (lazy restore) so agents can delete `agent/storage.ts`
+            // without losing durability while they still run architecture v1.
+            return defineStorage(Object.assign({ name: "cursor-hosted (lazy restore)", policy: { restore: "off" } }, cursorHostedStorage()));
+        }
+        return undefined;
+    }
+    if (input.authored !== undefined) {
+        // Discovery rejects agent/storage.ts on v2 before an engine is built;
+        // an authored definition reaching this point is a wiring bug. Raise
+        // rather than silently discard what the author believes is configured.
+        throw new Error('defineStorage (agent/storage.ts) is not supported on architecture "v2": storage is platform-selected. Delete the file.');
+    }
+    const hosting = resolveAgentV2Hosting({
+        architecture: input.architecture,
+        env: input.env,
+    });
+    if (hosting.kind !== "cursor-managed") {
+        // Self-hosted v2: the state root is the durable copy.
+        return undefined;
+    }
+    // Hosted v2 pods wake per delivery: bulk-restoring up to the default
+    // 1000 sessions on every boot is waste (and against the file-store
+    // backend it is per-key HTTP round trips before the listener even
+    // comes up). Follow-ups restore lazily by continuation or session id;
+    // GET /v1/sessions lists from the sink either way.
+    //
+    // Events flush at turn end. drainSessionDurability still forces the
+    // record onto the sink before the execution reply.
+    const policy = {
+        restore: "off",
+    };
+    // Full chain (env → bind file → stored login): frozen engines listen
+    // unsigned and bind store ids + CURSOR_API_KEY at task time, after this
+    // definition is constructed.
+    const resolveApiKey = () => { var _a; return (_a = resolveApiKeySync()) === null || _a === void 0 ? void 0 : _a.apiKey; };
+    // v2 pods carry a factorydb-bound service account, which the v1 Bugbot
+    // storage proxy cannot resolve; author KV, CAS coordination, and the
+    // eval/A-B tables speak the AgentSDK v2 KV proxy instead. It also carries
+    // the cursor-hosted marker, so GET /v1/sessions prefers the durable list
+    // (session records are on the framework store, which the composed core
+    // lists).
+    const kv = cursorHostedStorageV2({ resolveApiKey });
+    return defineStorage(Object.assign(Object.assign(Object.assign({ name: "cursor-hosted (framework files)", policy }, kv), composeFrameworkStorage({
+        kv,
+        files: fileSinkStorageCore(cursorHostedFiles({
+            resolveStoreSourceId: () => hosting.resolveStoreIds().frameworkStoreSourceId,
+            resolveApiKey,
+        })),
+    })), { 
+        // CAS stays on the KV proxy but must refuse framework-file keys, or a
+        // future coordination path would split-brain against the plain core.
+        cas: frameworkGuardedCas(kv.cas) }));
+}

package/dist/internal/frontmatter.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Frontmatter parsers. Authored markdown (skill descriptions, schedule cron
+ * expressions) uses the flat `key: value` scalar subset; Cursor plugin
+ * markdown is full YAML (folded descriptions, lists).
+ */
+export interface ParsedFrontmatter {
+    data: Record<string, string>;
+    body: string;
+}
+export interface ParsedYamlFrontmatter {
+    data: Record<string, unknown>;
+    body: string;
+    /** Why the block did not parse as a YAML mapping; `data` is then empty. */
+    error?: string;
+}
+/** YAML frontmatter with the JSON schema (no custom tags). */
+export declare function parseYamlFrontmatter(source: string): ParsedYamlFrontmatter;
+export declare function parseFrontmatter(source: string): ParsedFrontmatter;
+export declare function serializeFrontmatter(data: Record<string, string>): string;
+//# sourceMappingURL=frontmatter.d.ts.map

package/dist/internal/frontmatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter.d.ts","sourceRoot":"","sources":["../../src/internal/frontmatter.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAKD,8DAA8D;AAC9D,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,qBAAqB,CAoB1E;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB,CAsClE;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAGzE"}

package/dist/internal/frontmatter.js

@@ -0,0 +1,87 @@
+/**
+ * Frontmatter parsers. Authored markdown (skill descriptions, schedule cron
+ * expressions) uses the flat `key: value` scalar subset; Cursor plugin
+ * markdown is full YAML (folded descriptions, lists).
+ */
+import { JSON_SCHEMA, load as parseYaml } from "js-yaml";
+const FRONTMATTER_OPEN = /^---\s*$/;
+const YAML_FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)([\s\S]*)$/;
+/** YAML frontmatter with the JSON schema (no custom tags). */
+export function parseYamlFrontmatter(source) {
+    var _a, _b;
+    const match = YAML_FRONTMATTER.exec(source);
+    if (match === null) {
+        return { data: {}, body: source };
+    }
+    const body = (_a = match[2]) !== null && _a !== void 0 ? _a : "";
+    let data;
+    try {
+        data = parseYaml((_b = match[1]) !== null && _b !== void 0 ? _b : "", { schema: JSON_SCHEMA });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { data: {}, body, error: message };
+    }
+    if (data === undefined || data === null) {
+        return { data: {}, body };
+    }
+    if (typeof data !== "object" || Array.isArray(data)) {
+        return { data: {}, body, error: "frontmatter is not a mapping" };
+    }
+    return { data: data, body };
+}
+export function parseFrontmatter(source) {
+    var _a, _b;
+    const lines = source.split(/\r?\n/);
+    if (lines.length === 0 || !FRONTMATTER_OPEN.test((_a = lines[0]) !== null && _a !== void 0 ? _a : "")) {
+        return { data: {}, body: source };
+    }
+    let closeIndex = -1;
+    for (let i = 1; i < lines.length; i++) {
+        if (FRONTMATTER_OPEN.test((_b = lines[i]) !== null && _b !== void 0 ? _b : "")) {
+            closeIndex = i;
+            break;
+        }
+    }
+    if (closeIndex === -1) {
+        return { data: {}, body: source };
+    }
+    const data = {};
+    for (const line of lines.slice(1, closeIndex)) {
+        if (line.trim() === "" || line.trim().startsWith("#")) {
+            continue;
+        }
+        const separator = line.indexOf(":");
+        if (separator === -1) {
+            continue;
+        }
+        const key = line.slice(0, separator).trim();
+        if (key === "") {
+            continue;
+        }
+        data[key] = unquote(line.slice(separator + 1).trim());
+    }
+    const body = lines
+        .slice(closeIndex + 1)
+        .join("\n")
+        .replace(/^\n+/, "");
+    return { data, body };
+}
+export function serializeFrontmatter(data) {
+    const lines = Object.entries(data).map(([key, value]) => `${key}: ${quoteIfNeeded(value)}`);
+    return `---\n${lines.join("\n")}\n---\n`;
+}
+function unquote(value) {
+    if (value.length >= 2 &&
+        ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'")))) {
+        return value.slice(1, -1);
+    }
+    return value;
+}
+function quoteIfNeeded(value) {
+    if (/[:#'"\n]/.test(value)) {
+        return JSON.stringify(value);
+    }
+    return value;
+}