@cursor/july 0.1.95 → 0.1.96

package/dist/internal/cursor/backend-client.js

@@ -24,13 +24,9 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 import { randomUUID } from "node:crypto";
 import { z } from "zod";
 import { boundedToolAnnotations } from "../mcp-host.js";
+import { CURSOR_SESSION_EXCHANGE_PATH, CursorSessionExchangeError, exchangeCursorApiKeyForSession, SESSION_TOKEN_EXPIRY_LEEWAY_MS, } from "./session-token.js";
 const CLIENT_VERSION = "agent-serve-0.1.0";
-const EXCHANGE_PATH = "/auth/exchange_user_api_key";
 const SERVICE_PREFIX = "/aiserver.v1.DashboardService";
-/** Re-exchange when the cached token is within this window of expiry. */
-const TOKEN_EXPIRY_LEEWAY_MS = 5 * 60 * 1000;
-/** Fallback token lifetime when the JWT `exp` claim cannot be parsed. */
-const FALLBACK_TOKEN_LIFETIME_MS = 30 * 60 * 1000;
 const LIST_TIMEOUT_MS = 60000;
 /** Backend-executed tools call out to third-party servers; be generous. */
 const EXECUTE_TIMEOUT_MS = 120000;
@@ -374,7 +370,7 @@ export class CursorBackendClient {
             this.tokenExchange = undefined;
         }
         if (this.token !== undefined &&
-            Date.now() < this.token.expiresAtMs - TOKEN_EXPIRY_LEEWAY_MS) {
+            Date.now() < this.token.expiresAtMs - SESSION_TOKEN_EXPIRY_LEEWAY_MS) {
             return Promise.resolve(this.token.value);
         }
         // Single-flight: concurrent tool calls share one exchange.
@@ -388,38 +384,33 @@ export class CursorBackendClient {
     exchangeApiKey() {
         return __awaiter(this, void 0, void 0, function* () {
             const apiKey = this.currentApiKey();
-            let response;
+            let session;
             try {
-                response = yield this.fetchImpl(`${this.backendUrl}${EXCHANGE_PATH}`, {
-                    method: "POST",
-                    headers: {
-                        "content-type": "application/json",
-                        authorization: `Bearer ${apiKey}`,
-                    },
-                    body: "{}",
-                    signal: AbortSignal.timeout(30000),
+                session = yield exchangeCursorApiKeyForSession({
+                    exchangeUrl: `${this.backendUrl}${CURSOR_SESSION_EXCHANGE_PATH}`,
+                    apiKey,
+                    fetchImpl: this.fetchImpl,
                 });
             }
             catch (error) {
-                throw new CursorBackendError(`Could not reach the Cursor backend at ${this.backendUrl}: ${describeError(error)}`);
-            }
-            const text = yield response.text();
-            if (!response.ok) {
-                throw new CursorBackendError(response.status === 401
-                    ? "The Cursor API key was rejected. Run `agent-serve login` again or update CURSOR_API_KEY."
-                    : `Cursor API key exchange failed (${response.status}).`, response.status);
+                if (error instanceof CursorSessionExchangeError) {
+                    if (error.status === undefined) {
+                        throw new CursorBackendError(`Could not reach the Cursor backend at ${this.backendUrl}: ${error.message}`);
+                    }
+                    if (error.status >= 200 && error.status < 300) {
+                        // 2xx without a token in the body.
+                        throw new CursorBackendError("Cursor API key exchange returned no access token.");
+                    }
+                    throw new CursorBackendError(error.status === 401
+                        ? "The Cursor API key was rejected. Run `agent-serve login` again or update CURSOR_API_KEY."
+                        : `Cursor API key exchange failed (${error.status}).`, error.status);
+                }
+                throw error;
             }
-            const body = accessTokenResponseSchema.safeParse(safeJsonParse(text));
-            if (!body.success || body.data.accessToken === "") {
-                throw new CursorBackendError("Cursor API key exchange returned no access token.");
-            }
-            this.token = {
-                value: body.data.accessToken,
-                expiresAtMs: jwtExpiryMs(body.data.accessToken),
-            };
+            this.token = { value: session.token, expiresAtMs: session.expiresAtMs };
             this.lastExchangedApiKey = apiKey;
             this.logger("[agent-sdk] cursor account: minted a fresh access token");
-            return body.data.accessToken;
+            return session.token;
         });
     }
 }
@@ -502,7 +493,6 @@ export function revokeMintedUserApiKey(args) {
 // ============================================================================
 // Helpers
 // ============================================================================
-const accessTokenResponseSchema = z.object({ accessToken: z.string() });
 function safeJsonParse(text) {
     try {
         return JSON.parse(text);
@@ -648,22 +638,6 @@ function retryAfterMsFromResponse(response) {
     }
     return Math.min(retryAfter * 1000, MAX_GITHUB_TOKEN_RETRY_AFTER_MS);
 }
-function jwtExpiryMs(token) {
-    try {
-        const payload = token.split(".")[1];
-        if (payload === undefined) {
-            throw new Error("not a JWT");
-        }
-        const claims = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
-        if (typeof claims.exp === "number") {
-            return claims.exp * 1000;
-        }
-    }
-    catch (_a) {
-        // Opaque token — assume a conservative lifetime.
-    }
-    return Date.now() + FALLBACK_TOKEN_LIFETIME_MS;
-}
 function describeError(error) {
     return error instanceof Error ? error.message : String(error);
 }

package/dist/internal/cursor/session-token.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Shared `CURSOR_API_KEY` → Cursor session-token exchange primitive
+ * (`POST /auth/exchange_user_api_key`, ~1h session).
+ *
+ * Both `CursorBackendClient` (dashboard RPCs) and the Origin channel's
+ * session provider (`cursorSessionTokenProvider` in
+ * `../../channels/origin/api.ts`) mint through this module, so the URL,
+ * request shape, response parsing, JWT-expiry handling, and renewal
+ * constants cannot drift between the two. Callers own their caching and
+ * retry policies; this module owns exactly one exchange round trip.
+ */
+export declare const CURSOR_SESSION_EXCHANGE_PATH = "/auth/exchange_user_api_key";
+/** Re-exchange when the cached session is within this window of expiry. */
+export declare const SESSION_TOKEN_EXPIRY_LEEWAY_MS: number;
+/** Fallback session lifetime when the JWT `exp` claim cannot be parsed. */
+export declare const SESSION_TOKEN_FALLBACK_LIFETIME_MS: number;
+/**
+ * Exchange failure. `status` is the HTTP status when the backend answered,
+ * and undefined for network/transport errors. `detail` carries the server's
+ * `error` field when present so callers can surface the reason verbatim.
+ */
+export declare class CursorSessionExchangeError extends Error {
+    readonly status?: number | undefined;
+    readonly detail?: string | undefined;
+    constructor(message: string, status?: number | undefined, detail?: string | undefined);
+}
+/** Epoch-ms expiry from a JWT `exp` claim, or undefined when unparsable. */
+export declare function jwtExpiryMs(token: string): number | undefined;
+/**
+ * One exchange round trip. Throws {@link CursorSessionExchangeError} on
+ * transport failure, a non-2xx response, or a token-free body. `expiresAtMs`
+ * comes from the session JWT's `exp` claim, falling back to
+ * {@link SESSION_TOKEN_FALLBACK_LIFETIME_MS} for opaque tokens.
+ */
+export declare function exchangeCursorApiKeyForSession(args: {
+    /** Full exchange URL (base + {@link CURSOR_SESSION_EXCHANGE_PATH}). */
+    exchangeUrl: string;
+    apiKey: string;
+    fetchImpl?: typeof fetch;
+    nowMs?: number;
+}): Promise<{
+    token: string;
+    expiresAtMs: number;
+}>;
+//# sourceMappingURL=session-token.d.ts.map

package/dist/internal/cursor/session-token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-token.d.ts","sourceRoot":"","sources":["../../../src/internal/cursor/session-token.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,eAAO,MAAM,4BAA4B,gCAAgC,CAAC;AAC1E,2EAA2E;AAC3E,eAAO,MAAM,8BAA8B,EAAE,MAAsB,CAAC;AACpE,2EAA2E;AAC3E,eAAO,MAAM,kCAAkC,EAAE,MAAuB,CAAC;AAGzE;;;;GAIG;AACH,qBAAa,0BAA2B,SAAQ,KAAK;IAGjD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM;IAH1B,YACE,OAAO,EAAE,MAAM,EACN,MAAM,CAAC,EAAE,MAAM,YAAA,EACf,MAAM,CAAC,EAAE,MAAM,YAAA,EAIzB;CACF;AAED,4EAA4E;AAC5E,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAa7D;AAED;;;;;GAKG;AACH,wBAAsB,8BAA8B,CAAC,IAAI,EAAE;IACzD,uEAAuE;IACvE,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,CAmDlD"}

package/dist/internal/cursor/session-token.js

@@ -0,0 +1,99 @@
+/**
+ * Shared `CURSOR_API_KEY` → Cursor session-token exchange primitive
+ * (`POST /auth/exchange_user_api_key`, ~1h session).
+ *
+ * Both `CursorBackendClient` (dashboard RPCs) and the Origin channel's
+ * session provider (`cursorSessionTokenProvider` in
+ * `../../channels/origin/api.ts`) mint through this module, so the URL,
+ * request shape, response parsing, JWT-expiry handling, and renewal
+ * constants cannot drift between the two. Callers own their caching and
+ * retry policies; this module owns exactly one exchange round trip.
+ */
+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());
+    });
+};
+export const CURSOR_SESSION_EXCHANGE_PATH = "/auth/exchange_user_api_key";
+/** Re-exchange when the cached session is within this window of expiry. */
+export const SESSION_TOKEN_EXPIRY_LEEWAY_MS = 5 * 60 * 1000;
+/** Fallback session lifetime when the JWT `exp` claim cannot be parsed. */
+export const SESSION_TOKEN_FALLBACK_LIFETIME_MS = 30 * 60 * 1000;
+const EXCHANGE_TIMEOUT_MS = 30000;
+/**
+ * Exchange failure. `status` is the HTTP status when the backend answered,
+ * and undefined for network/transport errors. `detail` carries the server's
+ * `error` field when present so callers can surface the reason verbatim.
+ */
+export class CursorSessionExchangeError extends Error {
+    constructor(message, status, detail) {
+        super(message);
+        this.status = status;
+        this.detail = detail;
+        this.name = "CursorSessionExchangeError";
+    }
+}
+/** Epoch-ms expiry from a JWT `exp` claim, or undefined when unparsable. */
+export function jwtExpiryMs(token) {
+    try {
+        const payload = token.split(".")[1];
+        if (payload === undefined) {
+            return undefined;
+        }
+        const claims = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+        return typeof claims.exp === "number" ? claims.exp * 1000 : undefined;
+    }
+    catch (_a) {
+        return undefined;
+    }
+}
+/**
+ * One exchange round trip. Throws {@link CursorSessionExchangeError} on
+ * transport failure, a non-2xx response, or a token-free body. `expiresAtMs`
+ * comes from the session JWT's `exp` claim, falling back to
+ * {@link SESSION_TOKEN_FALLBACK_LIFETIME_MS} for opaque tokens.
+ */
+export function exchangeCursorApiKeyForSession(args) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b, _c;
+        const fetchImpl = (_a = args.fetchImpl) !== null && _a !== void 0 ? _a : fetch;
+        let response;
+        try {
+            response = yield fetchImpl(args.exchangeUrl, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    authorization: `Bearer ${args.apiKey}`,
+                },
+                body: "{}",
+                signal: AbortSignal.timeout(EXCHANGE_TIMEOUT_MS),
+            });
+        }
+        catch (error) {
+            throw new CursorSessionExchangeError(`Could not reach the Cursor session exchange at ${args.exchangeUrl}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const body = yield response.json().catch(() => undefined);
+        const record = typeof body === "object" && body !== null && !Array.isArray(body)
+            ? body
+            : {};
+        const detail = typeof record.error === "string" && record.error !== ""
+            ? record.error
+            : undefined;
+        if (!response.ok) {
+            throw new CursorSessionExchangeError(`Cursor session exchange failed with HTTP ${response.status}${detail === undefined ? "" : ` (${detail})`}.`, response.status, detail);
+        }
+        const token = record.accessToken;
+        if (typeof token !== "string" || token === "") {
+            throw new CursorSessionExchangeError("Cursor session exchange returned no access token.", response.status);
+        }
+        const nowMs = (_b = args.nowMs) !== null && _b !== void 0 ? _b : Date.now();
+        return {
+            token,
+            expiresAtMs: (_c = jwtExpiryMs(token)) !== null && _c !== void 0 ? _c : nowMs + SESSION_TOKEN_FALLBACK_LIFETIME_MS,
+        };
+    });
+}

package/dist/internal/cursor-agent-template.d.ts

@@ -1,4 +1,4 @@
-declare const TEMPLATE_NAMES: readonly ["agentic-owners", "demo", "pr-autofixer", "security-help", "security-reviewer", "triage-linear", "triage-jira"];
+declare const TEMPLATE_NAMES: readonly ["agentic-owners", "code-wiki", "demo", "pr-autofixer", "security-help", "security-reviewer", "triage-linear", "triage-jira"];
 export type TemplateName = (typeof TEMPLATE_NAMES)[number];
 export declare function canonicalTemplateName(name: string): string;
 export declare function isTemplateName(name: string): name is TemplateName;

package/dist/internal/cursor-agent-template.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cursor-agent-template.d.ts","sourceRoot":"","sources":["../../src/internal/cursor-agent-template.ts"],"names":[],"mappings":"AAIA,QAAA,MAAM,cAAc,YAClB,gBAAgB,EAChB,MAAM,EACN,cAAc,EACd,eAAe,EACf,mBAAmB,EACnB,eAAe,EACf,aAAa,CACL,CAAC;AACX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAG3D,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,YAAY,CAEjE;AAED,yEAAyE;AACzE,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAY3E;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAOtE"}
+{"version":3,"file":"cursor-agent-template.d.ts","sourceRoot":"","sources":["../../src/internal/cursor-agent-template.ts"],"names":[],"mappings":"AAIA,QAAA,MAAM,cAAc,YAClB,gBAAgB,EAChB,WAAW,EACX,MAAM,EACN,cAAc,EACd,eAAe,EACf,mBAAmB,EACnB,eAAe,EACf,aAAa,CACL,CAAC;AACX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAG3D,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,YAAY,CAEjE;AAED,yEAAyE;AACzE,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAY3E;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAOtE"}

package/dist/internal/cursor-agent-template.js

@@ -3,6 +3,7 @@ import { join } from "node:path";
 const MAX = 64;
 const TEMPLATE_NAMES = [
     "agentic-owners",
+    "code-wiki",
     "demo",
     "pr-autofixer",
     "security-help",

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

@@ -0,0 +1,61 @@
+/**
+ * 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,
+ *   the continuation index, and the SDK conversation mirror — and is never
+ *   exposed to authors or models.
+ *
+ * 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` / `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, A/B samples, 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.
+ */
+import type { FileSink } from "../files.js";
+import type { StorageConfig } from "../storage.js";
+/**
+ * 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 declare function isFrameworkFileKey(key: string): boolean;
+/** The KV core over a {@link FileSink}: one JSON document per key. */
+export type FileSinkStorageCore = Required<Pick<StorageConfig, "put" | "get" | "delete" | "list">>;
+export declare function fileSinkStorageCore(sink: FileSink): FileSinkStorageCore;
+/**
+ * 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` / `abs` groups (and the cursor-hosted
+ * marker) ride along untouched; wrap the KV `cas` group with
+ * {@link frameworkGuardedCas} rather than spreading it as-is.
+ */
+export declare function composeFrameworkStorage(input: {
+    kv: FileSinkStorageCore;
+    files: FileSinkStorageCore;
+}): FileSinkStorageCore;
+/**
+ * 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 declare function frameworkGuardedCas(cas: NonNullable<StorageConfig["cas"]>): NonNullable<StorageConfig["cas"]>;
+//# sourceMappingURL=framework-file-storage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"framework-file-storage.d.ts","sourceRoot":"","sources":["../../src/internal/framework-file-storage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,KAAK,EAAE,aAAa,EAAgB,MAAM,eAAe,CAAC;AAejE;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAavD;AAED,sEAAsE;AACtE,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CACxC,IAAI,CAAC,aAAa,EAAE,KAAK,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC,CACvD,CAAC;AA0BF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,QAAQ,GAAG,mBAAmB,CAuDvE;AAcD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE;IAC7C,EAAE,EAAE,mBAAmB,CAAC;IACxB,KAAK,EAAE,mBAAmB,CAAC;CAC5B,GAAG,mBAAmB,CAStB;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,WAAW,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,GACrC,WAAW,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CA0BnC"}

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

@@ -0,0 +1,204 @@
+/**
+ * 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,
+ *   the continuation index, and the SDK conversation mirror — and is never
+ *   exposed to authors or models.
+ *
+ * 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` / `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, A/B samples, 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 { STORAGE_KEY_ROOT } from "../storage-protocol.js";
+import { mapBounded } from "./bounded.js";
+/**
+ * Key kinds (`agentkit/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",
+    "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(`${STORAGE_KEY_ROOT}/`)) {
+        return false;
+    }
+    const rest = key.slice(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);
+}
+/**
+ * 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`.
+ */
+/** 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 === "..");
+}
+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, new TextEncoder().encode(JSON.stringify(value)));
+            });
+        },
+        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 each value is its own
+                // read; bound the fan-out — a bulk read here sits on restore paths.
+                const bodies = 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 decodeDocument(key, bytes) {
+    try {
+        return JSON.parse(new TextDecoder().decode(bytes));
+    }
+    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` / `abs` groups (and the cursor-hosted
+ * marker) ride 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),
+        get: (key, ctx) => route(key).get(key, ctx),
+        delete: (key, ctx) => route(key).delete(key, ctx),
+        list: (prefix, ctx) => route(prefix).list(prefix, ctx),
+    };
+}
+/**
+ * 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

@@ -17,11 +17,17 @@
  *
  * - **Cursor-managed hosting** (the deployment-generation environment
  *   variable is set, same signal that registers `GET /v1/manifest`):
- *   the Cursor-hosted backend, so session records, event chunks, `host.kv`,
- *   eval runs, and A/B samples land in the control plane and survive pod
- *   replacement. 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.
+ *   the Cursor-hosted backend. When the deployment carries a
+ *   **framework-level file store**
+ *   (`AGENT_SERVE_FRAMEWORK_STORE_SOURCE_ID`), session records, event
+ *   transcripts, and the continuation index live there — file-shaped state
+ *   on file storage, apart from the author-facing user store — while
+ *   `host.kv`, eval runs, A/B samples, and conditional writes stay on the
+ *   control-plane KV proxy (see framework-file-storage.ts). Without one
+ *   (a deploy predating framework-store provisioning), everything goes to
+ *   the KV proxy as before. 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.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"framework-storage-selection.d.ts","sourceRoot":"","sources":["../../src/internal/framework-storage-selection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAAiB,KAAK,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAEtE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAIrD,MAAM,WAAW,8BAA8B;IAC7C,2FAA2F;IAC3F,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,GAAG,SAAS,CAAC;IACjD,0DAA0D;IAC1D,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,CA2B/B"}
+{"version":3,"file":"framework-storage-selection.d.ts","sourceRoot":"","sources":["../../src/internal/framework-storage-selection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAMH,OAAO,EAAiB,KAAK,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAEtE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AASrD,MAAM,WAAW,8BAA8B;IAC7C,2FAA2F;IAC3F,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,GAAG,SAAS,CAAC;IACjD,0DAA0D;IAC1D,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,CAoD/B"}