@cursor/bdk 0.2.6 → 0.2.7

package/dist/internal/conversation-mirror.js

@@ -1,39 +1,13 @@
 /**
  * Durable mirror for the SDK runner's conversation store.
  *
- * The Cursor SDK keeps each local conversation in SQLite under the engine's
- * state root (`runner/index.db` + `runner/agents/agent-<hash>/store.db`).
- * That disk dies with the pod: on architecture v2, session **records** and
- * event chunks survive replacement through the control-plane storage mirror
- * (framework-storage-selection.ts), but the conversation itself was never
- * hydrated anywhere — a replacement pod resumed every thread as a fresh
- * conversation.
+ * The mirror restores checkpoint state before a conversation resumes and
+ * persists it after each local turn. Conversation data uses framework-owned
+ * storage, isolated from author-facing files and KV.
  *
- * This module mirrors the conversation through the SDK's own store APIs —
- * the agent document (which carries `sdkMetadata.blobEncryptionKey`, without
- * which the checkpoint blobs cannot be decrypted) plus its content-addressed
- * checkpoint blobs — into the deployment's **framework-level** file store
- * (`AGENT_SERVE_FRAMEWORK_STORE_SOURCE_ID`), alongside session records and
- * transcripts and apart from the author-facing user store. The store is an
- * Agent Store reached over `/v0/agent-serve-files` presigned URLs — **not
- * mounted** as a filesystem in the engine VM (the FUSE mount at
- * {@link DEPLOYMENT_STORE_MOUNT_PATH} exists only on cloud-runtime VMs) —
- * so the mirror moves bytes through the {@link FileSink} contract instead.
- *
- * Going through the store APIs rather than copying `store.db` files sidesteps
- * WAL consistency and the shared `index.db` (per-session raw copies would
- * clobber other sessions' rows); checkpoint blobs are content-addressed, so
- * repeat persists upload only what is new.
- *
- * Timing: the runner hydrates before `Agent.resume` (so a follow-up landing
- * on a fresh pod — including a v2 hosted-execution delivery — finds the
- * conversation before the turn runs) and persists after each local turn
- * settles, **awaited**, because a hosted pod can be parked immediately after
- * the execution reply.
- *
- * Run rows and run events are deliberately not mirrored: they are per-pod
- * bookkeeping (turn numbers, stream offsets), and the durable session event
- * stream already lives in the control-plane storage mirror.
+ * Restore failures propagate so a temporary storage outage cannot fork an
+ * existing thread into a fresh conversation. Run bookkeeping remains local;
+ * the durable session event stream already records user-visible history.
  */
 var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
     function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
@@ -117,7 +91,7 @@ export function createConversationMirror(options) {
             if (cached !== undefined) {
                 return cached;
             }
-            // Seed from the previous manifest so a fresh pod does not re-upload the
+            // Seed from the previous manifest so a new process does not re-upload the
             // whole history on its first persist. A miss, an unusable manifest, or
             // a failed read seeds empty — re-uploading is wasteful, never wrong.
             const seeded = new Set();
@@ -130,12 +104,52 @@ export function createConversationMirror(options) {
                 }
             }
             catch (error) {
-                logger(`[agent-sdk] conversation mirror: could not read the prior manifest for ${sdkAgentId} (${describeError(error)}); re-uploading blobs`);
+                logger(`[bdk] conversation mirror: could not read the prior manifest for ${sdkAgentId} (${describeError(error)}); re-uploading blobs`);
             }
             rememberMirrored(sdkAgentId, seeded);
             return seeded;
         });
     }
+    function uploadBlobs(store, sdkAgentId, blobIds, uploaded) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const entries = [];
+            for (const blobId of blobIds) {
+                const body = yield store.checkpoints.get({ agentId: sdkAgentId, blobId });
+                if (body !== null) {
+                    entries.push({
+                        blobId,
+                        key: agentSdkAgentStoreKeys.conversationBlob(agentName, sdkAgentId, blobId),
+                        body,
+                    });
+                }
+            }
+            if (entries.length === 0) {
+                return;
+            }
+            if (sink.putMany === undefined) {
+                for (const entry of entries) {
+                    yield sink.put(entry.key, entry.body);
+                    uploaded.add(entry.blobId);
+                }
+                return;
+            }
+            const settled = yield sink.putMany(entries.map(({ key, body }) => ({ key, body })));
+            let failure;
+            for (const [index, entry] of entries.entries()) {
+                const outcome = settled[index];
+                if ((outcome === null || outcome === void 0 ? void 0 : outcome.status) === "fulfilled") {
+                    uploaded.add(entry.blobId);
+                }
+                else if (failure === undefined) {
+                    failure = (_a = outcome === null || outcome === void 0 ? void 0 : outcome.reason) !== null && _a !== void 0 ? _a : new Error(`conversation mirror: batched upload of "${entry.key}" returned no outcome`);
+                }
+            }
+            if (failure !== undefined) {
+                throw failure;
+            }
+        });
+    }
     return {
         persist(store, sdkAgentId) {
             return serialize(sdkAgentId, () => __awaiter(this, void 0, void 0, function* () {
@@ -146,24 +160,13 @@ export function createConversationMirror(options) {
                 }
                 const uploaded = yield mirroredBlobIds(sdkAgentId);
                 const blobIds = yield listCheckpointBlobIds(store, sdkAgentId);
-                for (const blobId of blobIds) {
-                    if (uploaded.has(blobId)) {
-                        continue;
-                    }
-                    const bytes = yield store.checkpoints.get({
-                        agentId: sdkAgentId,
-                        blobId,
-                    });
-                    if (bytes === null) {
-                        continue;
-                    }
-                    yield sink.put(agentSdkAgentStoreKeys.conversationBlob(agentName, sdkAgentId, blobId), bytes);
-                    // Content-addressed: once in the sink, never re-uploaded.
-                    uploaded.add(blobId);
+                const pending = blobIds.filter(blobId => !uploaded.has(blobId));
+                for (let start = 0; start < pending.length; start += PERSIST_UPLOAD_BATCH_SIZE) {
+                    yield uploadBlobs(store, sdkAgentId, pending.slice(start, start + PERSIST_UPLOAD_BATCH_SIZE), uploaded);
                 }
                 const manifest = {
                     v: 1,
-                    // The referenced run is pod-local bookkeeping and is not mirrored;
+                    // The referenced run is process-local bookkeeping and is not mirrored;
                     // a hydrated store must not point at a run row it does not hold.
                     agent: Object.assign(Object.assign({}, document), { activeRunId: null }),
                     blobIds: blobIds.filter(blobId => uploaded.has(blobId)),
@@ -201,20 +204,17 @@ export function createConversationMirror(options) {
                     // during a rolling redeploy, or corruption): retrying would fail
                     // identically forever, so fall through to the caller's
                     // fresh-conversation path instead of wedging the session.
-                    logger(`[agent-sdk] conversation mirror: the manifest for ${sdkAgentId} is unusable (${read.reason}); treating the conversation as unrestorable`);
+                    logger(`[bdk] conversation mirror: the manifest for ${sdkAgentId} is unusable (${read.reason}); treating the conversation as unrestorable`);
                     return false;
                 }
                 const manifest = read.manifest;
                 const rootBlobId = (_a = manifest.agent.latestCheckpoint) === null || _a === void 0 ? void 0 : _a.rootBlobId;
                 if (rootBlobId === undefined || !manifest.blobIds.includes(rootBlobId)) {
-                    logger(`[agent-sdk] conversation mirror: the manifest for ${sdkAgentId} does not list its root checkpoint blob; treating the conversation as unrestorable`);
+                    logger(`[bdk] conversation mirror: the manifest for ${sdkAgentId} does not list its root checkpoint blob; treating the conversation as unrestorable`);
                     return false;
                 }
-                // This sits on the resume critical path. Prefer the sink's batched
-                // read — on the hosted sink that is one presign call per 100 blobs
-                // instead of one per blob, keeping a checkpoint-heavy restore under
-                // the store's per-deployment rate budget — and fall back to
-                // bounded-parallel per-blob gets elsewhere.
+                // This sits on the resume critical path. Prefer a batched read and
+                // fall back to bounded parallel reads when the sink has no batch API.
                 const blobKeys = manifest.blobIds.map(blobId => agentSdkAgentStoreKeys.conversationBlob(agentName, sdkAgentId, blobId));
                 const blobBodies = sink.getMany !== undefined
                     ? yield sink.getMany(blobKeys)
@@ -230,7 +230,7 @@ export function createConversationMirror(options) {
                     // may reach any listed blob, not just the root. Restoring a
                     // partial graph would create an agent row whose resume succeeds
                     // and whose checkpoint walk then fails unrecoverably.
-                    logger(`[agent-sdk] conversation mirror: ${missing.length} checkpoint blob(s) for ${sdkAgentId} are missing from the sink; treating the conversation as unrestorable`);
+                    logger(`[bdk] conversation mirror: ${missing.length} checkpoint blob(s) for ${sdkAgentId} are missing from the sink; treating the conversation as unrestorable`);
                     return false;
                 }
                 const restored = new Set();
@@ -253,7 +253,7 @@ export function createConversationMirror(options) {
                     agent: Object.assign(Object.assign({}, manifest.agent), { activeRunId: null }),
                 });
                 rememberMirrored(sdkAgentId, restored);
-                logger(`[agent-sdk] conversation mirror: restored the conversation for ${sdkAgentId} (${restored.size} checkpoint blob(s))`);
+                logger(`[bdk] conversation mirror: restored the conversation for ${sdkAgentId} (${restored.size} checkpoint blob(s))`);
                 return true;
             }));
         },
@@ -263,6 +263,7 @@ export function createConversationMirror(options) {
 const MAX_TRACKED_CONVERSATIONS = 1000;
 /** Parallel blob downloads during hydrate (resume critical path). */
 const HYDRATE_DOWNLOAD_CONCURRENCY = 8;
+const PERSIST_UPLOAD_BATCH_SIZE = 50;
 /**
  * Read the persisted manifest. Sink transport failures propagate (an
  * outage must fail the follow-up, not fork the thread); everything the
@@ -312,12 +313,9 @@ function listCheckpointBlobIds(store, sdkAgentId) {
 /**
  * Whether (and over which sink) this serve process mirrors conversations.
  *
- * Selected for architecture-v2 agents on Cursor-managed hosting — the same
- * generation signal as framework-storage-selection.ts, plus a provisioned
- * **framework-level** file store: conversation state is engine-owned, so it
- * lives with session records and transcripts, never on the author-facing
- * user store. Self-hosted v2 keeps everything on the state root (the
- * operator owns the disk), and v1 keeps today's behavior while it runs.
+ * Enabled for architecture-v2 agents on Cursor-managed hosting.
+ * Conversation state is framework-owned and never uses author-facing
+ * storage. Self-hosted and architecture-v1 agents keep local behavior.
  */
 export function selectConversationMirror(input) {
     const hosting = resolveAgentV2Hosting({
@@ -330,10 +328,6 @@ export function selectConversationMirror(input) {
     return createConversationMirror({
         sink: cursorHostedFiles({
             resolveStoreSourceId: () => hosting.resolveStoreIds().frameworkStoreSourceId,
-            // Full chain (env → key file → stored login), resolved lazily: frozen
-            // engines listen unsigned and only gain a credential at task time,
-            // after this sink is constructed. Hosted deliveries have consumed the
-            // bind file into CURSOR_API_KEY by then, so this resolves from env.
             resolveApiKey: () => { var _a; return (_a = resolveApiKeySync()) === null || _a === void 0 ? void 0 : _a.apiKey; },
         }),
         agentName: input.project.name,

package/dist/internal/cursor/account-mcp.d.ts

@@ -116,7 +116,7 @@ export interface CursorAccountMcpWarningServer {
 }
 /**
  * Yellow warning panel for unhealthy / missing Cursor-account connectors.
- * One box replaces the old stacked `[agent-sdk]` log lines.
+ * One box replaces the old stacked `[bdk]` log lines.
  */
 export declare function formatCursorAccountMcpWarningBox(args: {
     connectionName: string;

package/dist/internal/cursor/account-mcp.js

@@ -413,7 +413,7 @@ function connectUrl(authUrl) {
 }
 /**
  * Yellow warning panel for unhealthy / missing Cursor-account connectors.
- * One box replaces the old stacked `[agent-sdk]` log lines.
+ * One box replaces the old stacked `[bdk]` log lines.
  */
 export function formatCursorAccountMcpWarningBox(args) {
     var _a, _b;

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

@@ -481,7 +481,7 @@ export class CursorBackendClient {
             }
             this.token = { value: session.token, expiresAtMs: session.expiresAtMs };
             this.lastExchangedApiKey = apiKey;
-            this.logger("[agent-sdk] cursor account: minted a fresh access token");
+            this.logger("[bdk] cursor account: minted a fresh access token");
             return session.token;
         });
     }

package/dist/internal/cursor/github-credentials.js

@@ -112,13 +112,13 @@ export class CursorGithubCredentialProvider {
                     this.installGhToken(result.token);
                     this.scheduleRefresh();
                 }
-                this.logger(`[agent-sdk] GitHub auth: refreshed Cursor account credential for ${this.repos.length} repo(s)`);
+                this.logger(`[bdk] GitHub auth: refreshed Cursor account credential for ${this.repos.length} repo(s)`);
                 return result.token;
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
                 if (this.cached !== undefined && this.now() < this.cached.expiresAtMs) {
-                    this.logger(`[agent-sdk] GitHub auth: Cursor account credential refresh failed; using the current lease: ${message}`);
+                    this.logger(`[bdk] GitHub auth: Cursor account credential refresh failed; using the current lease: ${message}`);
                     this.cached.refreshAtMs = Math.min(this.cached.expiresAtMs, this.now() + REFRESH_RETRY_MS);
                     if (this.started) {
                         this.scheduleRetry();
@@ -161,7 +161,7 @@ export class CursorGithubCredentialProvider {
         }
         this.refreshTimer = setTimeout(() => {
             void this.getToken().catch((error) => {
-                this.logger(`[agent-sdk] GitHub auth: Cursor account credential refresh failed: ${error instanceof Error ? error.message : String(error)}`);
+                this.logger(`[bdk] GitHub auth: Cursor account credential refresh failed: ${error instanceof Error ? error.message : String(error)}`);
                 this.scheduleRetry();
             });
         }, delayMs);

package/dist/internal/cursor/hosted-bound-secrets.d.ts

@@ -12,15 +12,19 @@
  * It fails closed. A secret that survives the consume would sit world-readable
  * next to authored agent code for the length of a turn, so the caller returns
  * a retryable error instead of dispatching. The next request re-binds and
- * consumes again.
+ * consumes again. So does a request that ends up with no Cursor API key at
+ * all: the control plane skips the bind while it believes this process holds
+ * one, and a process that restarted in place lost it.
  */
 /** Wire error code for a bind file that outlived its consume. */
 export declare const BOUND_SECRETS_NOT_CONSUMED = "bound_secrets_not_consumed";
+/** Wire error code for a request that reached authored code with no API key bound. */
+export declare const BOUND_SECRETS_MISSING = "bound_secrets_missing";
 export type HostedBoundSecretsResult = {
     ok: true;
 } | {
     ok: false;
-    code: typeof BOUND_SECRETS_NOT_CONSUMED;
+    code: typeof BOUND_SECRETS_NOT_CONSUMED | typeof BOUND_SECRETS_MISSING;
     message: string;
 };
 /**

package/dist/internal/cursor/hosted-bound-secrets.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hosted-bound-secrets.d.ts","sourceRoot":"","sources":["../../../src/internal/cursor/hosted-bound-secrets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAQH,iEAAiE;AACjE,eAAO,MAAM,0BAA0B,+BAA+B,CAAC;AAEvE,MAAM,MAAM,wBAAwB,GAChC;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GACZ;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,OAAO,0BAA0B,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5E;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,CAAC,EAAE;IAClD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,yBAAyB,CAAC,EAAE,MAAM,CAAC;CACpC,GAAG,wBAAwB,CA0B3B"}
+{"version":3,"file":"hosted-bound-secrets.d.ts","sourceRoot":"","sources":["../../../src/internal/cursor/hosted-bound-secrets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAQH,iEAAiE;AACjE,eAAO,MAAM,0BAA0B,+BAA+B,CAAC;AAEvE,sFAAsF;AACtF,eAAO,MAAM,qBAAqB,0BAA0B,CAAC;AAE7D,MAAM,MAAM,wBAAwB,GAChC;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GACZ;IACE,EAAE,EAAE,KAAK,CAAC;IACV,IAAI,EAAE,OAAO,0BAA0B,GAAG,OAAO,qBAAqB,CAAC;IACvE,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEN;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,CAAC,EAAE;IAClD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,yBAAyB,CAAC,EAAE,MAAM,CAAC;CACpC,GAAG,wBAAwB,CAiC3B"}

package/dist/internal/cursor/hosted-bound-secrets.js

@@ -12,12 +12,16 @@
  * It fails closed. A secret that survives the consume would sit world-readable
  * next to authored agent code for the length of a turn, so the caller returns
  * a retryable error instead of dispatching. The next request re-binds and
- * consumes again.
+ * consumes again. So does a request that ends up with no Cursor API key at
+ * all: the control plane skips the bind while it believes this process holds
+ * one, and a process that restarted in place lost it.
  */
 import { consumeBoundCursorApiKey, DEFAULT_CURSOR_API_KEY_FILE } from "./credentials.js";
 import { consumeBoundDeploymentSecrets, DEFAULT_AGENT_SERVE_DEPLOYMENT_SECRETS_FILE, } from "./hosted-deployment-secrets.js";
 /** Wire error code for a bind file that outlived its consume. */
 export const BOUND_SECRETS_NOT_CONSUMED = "bound_secrets_not_consumed";
+/** Wire error code for a request that reached authored code with no API key bound. */
+export const BOUND_SECRETS_MISSING = "bound_secrets_missing";
 /**
  * Hydrate `process.env` from both bind files and remove them from disk.
  * Returns a failure when either secret is still readable afterwards.
@@ -30,7 +34,7 @@ export const BOUND_SECRETS_NOT_CONSUMED = "bound_secrets_not_consumed";
  * file on a surface that points the variable at one.
  */
 export function consumeHostedBoundSecrets(options) {
-    var _a, _b;
+    var _a, _b, _c;
     const survivors = [];
     const secretsPath = (_a = options === null || options === void 0 ? void 0 : options.deploymentSecretsFilePath) !== null && _a !== void 0 ? _a : DEFAULT_AGENT_SERVE_DEPLOYMENT_SECRETS_FILE;
     const secrets = consumeBoundDeploymentSecrets(secretsPath);
@@ -43,6 +47,13 @@ export function consumeHostedBoundSecrets(options) {
         survivors.push(`${apiKeyPath} (${apiKey.disposal.reason})`);
     }
     if (survivors.length === 0) {
+        if (((_c = process.env.CURSOR_API_KEY) !== null && _c !== void 0 ? _c : "").trim() === "") {
+            return {
+                ok: false,
+                code: BOUND_SECRETS_MISSING,
+                message: "No Cursor API key is bound to this process, so authored work did not run.",
+            };
+        }
         return { ok: true };
     }
     return {

package/dist/internal/cursor/hosted-store-secrets.d.ts

@@ -1,52 +1,30 @@
 /**
- * Task-time bind paths for hosted deployment file-store source ids.
- *
- * Freeze v2 snapshots start `agent-sdk serve` at bake time without a service
- * account, so neither store id is in process env. Execute-from-freeze binds
- * the deployment credential and store ids into `/run/cursor/secrets/` without
- * restarting July — the same pattern as {@link DEFAULT_CURSOR_API_KEY_FILE}.
+ * Resolves platform-managed storage bindings for hosted deployments.
  */
 export declare const DEFAULT_AGENT_SERVE_STORE_SOURCE_ID_FILE = "/run/cursor/secrets/AGENT_SERVE_STORE_SOURCE_ID";
 export declare const DEFAULT_AGENT_SERVE_FRAMEWORK_STORE_SOURCE_ID_FILE = "/run/cursor/secrets/AGENT_SERVE_FRAMEWORK_STORE_SOURCE_ID";
 export declare const DEFAULT_AGENT_SERVE_STORE_PROTOCOL_FILE = "/run/cursor/secrets/AGENT_SERVE_STORE_PROTOCOL";
 /**
- * Pin value selecting the factory store API (`/internal/agentsdk/store`)
- * over `/v0/agent-serve-files`. Any other value — including a newer pin this
- * runtime does not know — falls back to `/v0`, so the pin fails safe in both
- * directions.
+ * Transport mode that enables batched file operations. Unknown values use
+ * the compatibility transport.
  */
 export declare const AGENT_SERVE_FACTORY_FLUSH_PROTOCOL = "factory-flush-v1";
 /**
- * Pin value additionally enabling the domain-call lane
- * (`POST /internal/agentsdk/store/api/<call>`), where the server owns the
- * storage pattern for framework state — starting with `memory.append`. A
- * strict superset of {@link AGENT_SERVE_FACTORY_FLUSH_PROTOCOL}: verbs keep
- * riding the factory flush wire under this pin too. The same fail-safe
- * applies in both directions — an unknown value keeps today's behavior, and
- * re-pinning to `factory-flush-v1` turns the domain lane back off without a
- * client change.
+ * Transport mode that adds managed domain operations to
+ * {@link AGENT_SERVE_FACTORY_FLUSH_PROTOCOL}.
  */
 export declare const AGENT_SERVE_FACTORY_API_PROTOCOL = "factory-api-v1";
-/**
- * Does this pin select the factory flush wire for the store verbs? True for
- * the flush pin and for the domain-API superset pin.
- */
+/** True when the transport supports batched file operations. */
 export declare function storeProtocolEnablesFactoryFlush(protocol: string | undefined): boolean;
-/**
- * Does this pin enable the domain-call lane (server-owned storage patterns)?
- * Only its exact value does; everything else keeps the client-side patterns.
- */
+/** True when the transport supports managed domain operations. */
 export declare function storeProtocolEnablesStoreApi(protocol: string | undefined): boolean;
-/** Deployment user-land store: env, then task-bind file. */
+/** Resolve the author-facing managed file store. */
 export declare function resolveDeploymentStoreSourceIdSync(env?: NodeJS.ProcessEnv): string | undefined;
-/** Engine framework store: env, then task-bind file. */
+/** Resolve the framework-only managed file store. */
 export declare function resolveFrameworkStoreSourceIdSync(env?: NodeJS.ProcessEnv): string | undefined;
 /**
- * Store protocol pin: env, then task-bind file. The control plane binds
- * `factory-flush-v1` on every hosted v2 pod. Absence or an unknown value
- * still means `/v0/agent-serve-files`. Resolved lazily per operation like
- * the store ids, so a pod bound after serve start takes effect without a
- * restart.
+ * Resolve the managed-storage transport mode. Callers resolve it lazily so
+ * platform updates take effect without recreating the storage client.
  */
 export declare function resolveStoreProtocolSync(env?: NodeJS.ProcessEnv): string | undefined;
 export type CursorManagedV2StoreIds = {
@@ -54,10 +32,8 @@ export type CursorManagedV2StoreIds = {
     frameworkStoreSourceId: string;
 };
 /**
- * Resolve the complete managed-v2 store identity at the process boundary.
- *
- * Freeze snapshots construct storage before task bind, so callers keep this
- * resolver lazy. Once an operation needs storage, both ids are mandatory.
+ * Resolve both managed architecture-v2 storage identities. Callers keep this
+ * resolver lazy, and both identities are mandatory once storage is used.
  */
 export declare function requireCursorManagedV2StoreIdsSync(env?: NodeJS.ProcessEnv): CursorManagedV2StoreIds;
 //# sourceMappingURL=hosted-store-secrets.d.ts.map

package/dist/internal/cursor/hosted-store-secrets.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hosted-store-secrets.d.ts","sourceRoot":"","sources":["../../../src/internal/cursor/hosted-store-secrets.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,eAAO,MAAM,wCAAwC,oDACF,CAAC;AAEpD,eAAO,MAAM,kDAAkD,8DACF,CAAC;AAE9D,eAAO,MAAM,uCAAuC,mDACF,CAAC;AAEnD;;;;;GAKG;AACH,eAAO,MAAM,kCAAkC,qBAAqB,CAAC;AAErE;;;;;;;;;GASG;AACH,eAAO,MAAM,gCAAgC,mBAAmB,CAAC;AAEjE;;;GAGG;AACH,wBAAgB,gCAAgC,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAItF;AAED;;;GAGG;AACH,wBAAgB,4BAA4B,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAElF;AA4BD,4DAA4D;AAC5D,wBAAgB,kCAAkC,CAChD,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,GAAG,SAAS,CAUpB;AAED,wDAAwD;AACxD,wBAAgB,iCAAiC,CAC/C,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,GAAG,SAAS,CAUpB;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,GAAG,SAAS,CAMjG;AAED,MAAM,MAAM,uBAAuB,GAAG;IACpC,uBAAuB,EAAE,MAAM,CAAC;IAChC,sBAAsB,EAAE,MAAM,CAAC;CAChC,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,kCAAkC,CAChD,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,uBAAuB,CASzB"}
+{"version":3,"file":"hosted-store-secrets.d.ts","sourceRoot":"","sources":["../../../src/internal/cursor/hosted-store-secrets.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,eAAO,MAAM,wCAAwC,oDACF,CAAC;AAEpD,eAAO,MAAM,kDAAkD,8DACF,CAAC;AAE9D,eAAO,MAAM,uCAAuC,mDACF,CAAC;AAEnD;;;GAGG;AACH,eAAO,MAAM,kCAAkC,qBAAqB,CAAC;AAErE;;;GAGG;AACH,eAAO,MAAM,gCAAgC,mBAAmB,CAAC;AAEjE,gEAAgE;AAChE,wBAAgB,gCAAgC,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAItF;AAED,kEAAkE;AAClE,wBAAgB,4BAA4B,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAElF;AA4BD,oDAAoD;AACpD,wBAAgB,kCAAkC,CAChD,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,GAAG,SAAS,CAUpB;AAED,qDAAqD;AACrD,wBAAgB,iCAAiC,CAC/C,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,GAAG,SAAS,CAUpB;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,GAAG,SAAS,CAMjG;AAED,MAAM,MAAM,uBAAuB,GAAG;IACpC,uBAAuB,EAAE,MAAM,CAAC;IAChC,sBAAsB,EAAE,MAAM,CAAC;CAChC,CAAC;AAEF;;;GAGG;AACH,wBAAgB,kCAAkC,CAChD,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,uBAAuB,CASzB"}

package/dist/internal/cursor/hosted-store-secrets.js

@@ -1,44 +1,25 @@
 /**
- * Task-time bind paths for hosted deployment file-store source ids.
- *
- * Freeze v2 snapshots start `agent-sdk serve` at bake time without a service
- * account, so neither store id is in process env. Execute-from-freeze binds
- * the deployment credential and store ids into `/run/cursor/secrets/` without
- * restarting July — the same pattern as {@link DEFAULT_CURSOR_API_KEY_FILE}.
+ * Resolves platform-managed storage bindings for hosted deployments.
  */
 import { readFileSync } from "node:fs";
 export const DEFAULT_AGENT_SERVE_STORE_SOURCE_ID_FILE = "/run/cursor/secrets/AGENT_SERVE_STORE_SOURCE_ID";
 export const DEFAULT_AGENT_SERVE_FRAMEWORK_STORE_SOURCE_ID_FILE = "/run/cursor/secrets/AGENT_SERVE_FRAMEWORK_STORE_SOURCE_ID";
 export const DEFAULT_AGENT_SERVE_STORE_PROTOCOL_FILE = "/run/cursor/secrets/AGENT_SERVE_STORE_PROTOCOL";
 /**
- * Pin value selecting the factory store API (`/internal/agentsdk/store`)
- * over `/v0/agent-serve-files`. Any other value — including a newer pin this
- * runtime does not know — falls back to `/v0`, so the pin fails safe in both
- * directions.
+ * Transport mode that enables batched file operations. Unknown values use
+ * the compatibility transport.
  */
 export const AGENT_SERVE_FACTORY_FLUSH_PROTOCOL = "factory-flush-v1";
 /**
- * Pin value additionally enabling the domain-call lane
- * (`POST /internal/agentsdk/store/api/<call>`), where the server owns the
- * storage pattern for framework state — starting with `memory.append`. A
- * strict superset of {@link AGENT_SERVE_FACTORY_FLUSH_PROTOCOL}: verbs keep
- * riding the factory flush wire under this pin too. The same fail-safe
- * applies in both directions — an unknown value keeps today's behavior, and
- * re-pinning to `factory-flush-v1` turns the domain lane back off without a
- * client change.
+ * Transport mode that adds managed domain operations to
+ * {@link AGENT_SERVE_FACTORY_FLUSH_PROTOCOL}.
  */
 export const AGENT_SERVE_FACTORY_API_PROTOCOL = "factory-api-v1";
-/**
- * Does this pin select the factory flush wire for the store verbs? True for
- * the flush pin and for the domain-API superset pin.
- */
+/** True when the transport supports batched file operations. */
 export function storeProtocolEnablesFactoryFlush(protocol) {
     return (protocol === AGENT_SERVE_FACTORY_FLUSH_PROTOCOL || protocol === AGENT_SERVE_FACTORY_API_PROTOCOL);
 }
-/**
- * Does this pin enable the domain-call lane (server-owned storage patterns)?
- * Only its exact value does; everything else keeps the client-side patterns.
- */
+/** True when the transport supports managed domain operations. */
 export function storeProtocolEnablesStoreApi(protocol) {
     return protocol === AGENT_SERVE_FACTORY_API_PROTOCOL;
 }
@@ -63,7 +44,7 @@ function readBoundSecretFile(fileEnvVar, defaultPath, env) {
     const path = configured !== undefined && configured !== "" ? configured : defaultPath;
     return readTrimmedFile(path);
 }
-/** Deployment user-land store: env, then task-bind file. */
+/** Resolve the author-facing managed file store. */
 export function resolveDeploymentStoreSourceIdSync(env = process.env) {
     var _a;
     const fromEnv = (_a = env[STORE_SOURCE_ID_ENV]) === null || _a === void 0 ? void 0 : _a.trim();
@@ -72,7 +53,7 @@ export function resolveDeploymentStoreSourceIdSync(env = process.env) {
     }
     return readBoundSecretFile(STORE_SOURCE_ID_FILE_ENV, DEFAULT_AGENT_SERVE_STORE_SOURCE_ID_FILE, env);
 }
-/** Engine framework store: env, then task-bind file. */
+/** Resolve the framework-only managed file store. */
 export function resolveFrameworkStoreSourceIdSync(env = process.env) {
     var _a;
     const fromEnv = (_a = env[FRAMEWORK_STORE_SOURCE_ID_ENV]) === null || _a === void 0 ? void 0 : _a.trim();
@@ -82,11 +63,8 @@ export function resolveFrameworkStoreSourceIdSync(env = process.env) {
     return readBoundSecretFile(FRAMEWORK_STORE_SOURCE_ID_FILE_ENV, DEFAULT_AGENT_SERVE_FRAMEWORK_STORE_SOURCE_ID_FILE, env);
 }
 /**
- * Store protocol pin: env, then task-bind file. The control plane binds
- * `factory-flush-v1` on every hosted v2 pod. Absence or an unknown value
- * still means `/v0/agent-serve-files`. Resolved lazily per operation like
- * the store ids, so a pod bound after serve start takes effect without a
- * restart.
+ * Resolve the managed-storage transport mode. Callers resolve it lazily so
+ * platform updates take effect without recreating the storage client.
  */
 export function resolveStoreProtocolSync(env = process.env) {
     var _a;
@@ -97,10 +75,8 @@ export function resolveStoreProtocolSync(env = process.env) {
     return readBoundSecretFile(STORE_PROTOCOL_FILE_ENV, DEFAULT_AGENT_SERVE_STORE_PROTOCOL_FILE, env);
 }
 /**
- * Resolve the complete managed-v2 store identity at the process boundary.
- *
- * Freeze snapshots construct storage before task bind, so callers keep this
- * resolver lazy. Once an operation needs storage, both ids are mandatory.
+ * Resolve both managed architecture-v2 storage identities. Callers keep this
+ * resolver lazy, and both identities are mandatory once storage is used.
  */
 export function requireCursorManagedV2StoreIdsSync(env = process.env) {
     const deploymentStoreSourceId = resolveDeploymentStoreSourceIdSync(env);

package/dist/internal/cursor/store-api-client.d.ts

@@ -1,29 +1,17 @@
 /**
- * The store API client: July's one gateway to the factory domain-call lane,
- * `POST /internal/agentsdk/store/api/<call>`. This module owns the whole
- * transport — base URL and deployment credential (the same resolution the
- * files sink uses, via `cursor-api-transport.ts`), envelope encoding,
- * response validation, typed error mapping, and the bounded backoff policy.
- * Feature modules (`memory.ts`, later `session-run-log.ts`, …) call typed
- * methods like {@link StoreApiClient.memoryAppend} and never hand-roll
- * fetch; future domain calls (`sessionRun.report`, `startLog.flush`, …) are
- * added here as new methods on this one client.
+ * Client for versioned Cursor-managed store operations.
  *
- * The lane is selected per pod by the task-bound store protocol pin:
- * {@link isStoreApiLaneEnabled} is true only under the exact
- * `factory-api-v1` pin AND with a provisioned deployment store. The
- * availability check is not redundant: the pin file is written by the hosted
- * task bind, but a local-dev env var could name the pin without any store to
- * serve reads — appending into the void. Both resolve lazily per call, so a
- * pin bound after serve start takes effect without a restart.
+ * This module owns transport, envelope encoding, response validation, typed
+ * errors, and bounded retries. Availability requires both a compatible
+ * transport and a managed store, resolved lazily for each call.
  */
 import { type CursorApiTransportOptions } from "./cursor-api-transport.js";
 export interface StoreApiClientOptions extends CursorApiTransportOptions {
-    /** Deployment store source id override (lane availability check). */
+    /** Managed store binding override. */
     storeSourceId?: string;
     /** Lazy store source id, preferred over {@link storeSourceId}. */
     resolveStoreSourceId?: () => string | undefined;
-    /** Lazy store protocol pin (default: env, then the task-bound file). */
+    /** Lazy transport selection override. */
     resolveStoreProtocol?: () => string | undefined;
     /** Backoff sleep override (tests). */
     sleep?: (ms: number) => Promise<void>;
@@ -33,14 +21,13 @@ export interface StoreApiClientOptions extends CursorApiTransportOptions {
 /**
  * How one domain call failed, after the client's bounded retries:
  *
- * - `rejected` — the server (or the client's own pre-check) refused the
+ * - `rejected`: the server (or the client's own pre-check) refused the
  *   payload with a typed 4xx. Deterministic; never retried.
- * - `shed` — 429 from the per-deployment limiter or kill switch. Retried
- *   only within the small Retry-After bound below; retrying harder against
- *   a shed is exactly the stampede the domain lane exists to prevent.
- * - `unavailable` — 5xx or a network failure, retried up to the attempt
+ * - `shed`: a rate-limited request. Retried only within the small
+ *   Retry-After bound below.
+ * - `unavailable`: 5xx or a network failure, retried up to the attempt
  *   bound.
- * - `bad_response` — a 2xx whose body failed the response schema; a
+ * - `bad_response`: a 2xx whose body failed the response schema; a
  *   contract break, not a transient, so never retried.
  */
 export type StoreApiFailureKind = "rejected" | "shed" | "unavailable" | "bad_response";
@@ -49,30 +36,21 @@ export declare class StoreApiCallError extends Error {
     readonly status?: number | undefined;
     constructor(kind: StoreApiFailureKind, message: string, status?: number | undefined);
 }
-/**
- * Is the domain-call lane on for this pod? Exact pin match plus a
- * provisioned deployment store; anything else keeps the client-side
- * patterns, fail-safe in both directions like the flush pin itself.
- */
+/** True when managed store operations are available. */
 export declare function isStoreApiLaneEnabled(options?: StoreApiClientOptions): boolean;
 export type StoreApiClient = {
     /**
-     * One `memory.append` domain call: the server appends the record to a
-     * server-owned journal shard. Resolves on success; throws
-     * {@link StoreApiCallError} after the bounded retries. The caller owns the
-     * failure policy (memory drops the record — appending is advisory).
+     * Append one advisory memory record. Resolves when managed storage accepts
+     * it; throws {@link StoreApiCallError} after bounded retries.
      */
     memoryAppend(payload: {
         agent: string;
         record: Record<string, unknown>;
     }): Promise<void>;
     /**
-     * One `memory.read` domain call plus the presigned byte fetch: the server
-     * flushes the agent's pending append buffer (best-effort) and presigns
-     * the canonical journal; this method then downloads it. Undefined while
-     * the agent has no journal. Throws {@link StoreApiCallError} after the
-     * bounded retries — the caller owns the failure policy (hydration keeps
-     * the existing mirror).
+     * Read a best-effort memory snapshot. It may lag accepted appends, so the
+     * caller retains a longer local view. Returns `undefined` when no journal
+     * exists and throws {@link StoreApiCallError} after bounded retries.
      */
     memoryReadContent(payload: {
         agent: string;

package/dist/internal/cursor/store-api-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"store-api-client.d.ts","sourceRoot":"","sources":["../../../src/internal/cursor/store-api-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAYH,OAAO,EACL,KAAK,yBAAyB,EAI/B,MAAM,2BAA2B,CAAC;AAOnC,MAAM,WAAW,qBAAsB,SAAQ,yBAAyB;IACtE,qEAAqE;IACrE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kEAAkE;IAClE,oBAAoB,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IAChD,wEAAwE;IACxE,oBAAoB,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IAChD,sCAAsC;IACtC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,mBAAmB,GAAG,UAAU,GAAG,MAAM,GAAG,aAAa,GAAG,cAAc,CAAC;AAEvF,qBAAa,iBAAkB,SAAQ,KAAK;IAExC,QAAQ,CAAC,IAAI,EAAE,mBAAmB;IAElC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM;IAH1B,YACW,IAAI,EAAE,mBAAmB,EAClC,OAAO,EAAE,MAAM,EACN,MAAM,CAAC,EAAE,MAAM,YAAA,EAIzB;CACF;AA0BD;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,GAAE,qBAA0B,GAAG,OAAO,CAWlF;AAED,MAAM,MAAM,cAAc,GAAG;IAC3B;;;;;OAKG;IACH,YAAY,CAAC,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzF;;;;;;;OAOG;IACH,iBAAiB,CAAC,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAAC;CAChF,CAAC;AAEF,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,qBAA0B,GAAG,cAAc,CAoLxF"}
+{"version":3,"file":"store-api-client.d.ts","sourceRoot":"","sources":["../../../src/internal/cursor/store-api-client.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAYH,OAAO,EACL,KAAK,yBAAyB,EAI/B,MAAM,2BAA2B,CAAC;AAOnC,MAAM,WAAW,qBAAsB,SAAQ,yBAAyB;IACtE,sCAAsC;IACtC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kEAAkE;IAClE,oBAAoB,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IAChD,yCAAyC;IACzC,oBAAoB,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IAChD,sCAAsC;IACtC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,mBAAmB,GAAG,UAAU,GAAG,MAAM,GAAG,aAAa,GAAG,cAAc,CAAC;AAEvF,qBAAa,iBAAkB,SAAQ,KAAK;IAExC,QAAQ,CAAC,IAAI,EAAE,mBAAmB;IAElC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM;IAH1B,YACW,IAAI,EAAE,mBAAmB,EAClC,OAAO,EAAE,MAAM,EACN,MAAM,CAAC,EAAE,MAAM,YAAA,EAIzB;CACF;AAsBD,wDAAwD;AACxD,wBAAgB,qBAAqB,CAAC,OAAO,GAAE,qBAA0B,GAAG,OAAO,CAWlF;AAED,MAAM,MAAM,cAAc,GAAG;IAC3B;;;OAGG;IACH,YAAY,CAAC,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzF;;;;OAIG;IACH,iBAAiB,CAAC,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAAC;CAChF,CAAC;AAEF,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,qBAA0B,GAAG,cAAc,CAkLxF"}