@cursor/bdk 0.2.1

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

@@ -0,0 +1,191 @@
+/**
+ * Short-lived GitHub credentials minted from the host's Cursor account.
+ *
+ * The token stays in memory. `GH_TOKEN` is updated for child `gh` processes,
+ * while Octokit callers use {@link getToken} so long-lived clients refresh
+ * without being rebuilt.
+ */
+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 { CursorBackendError } from "./backend-client.js";
+const REFRESH_LEEWAY_MS = 5 * 60000;
+const REFRESH_RETRY_MS = 60000;
+const FAILURE_CACHE_TTL_MS = 60000;
+const MAX_RETRY_AFTER_MS = 60 * 60000;
+const MIN_TIMER_DELAY_MS = 1000;
+export class CursorGithubCredentialProvider {
+    constructor(options) {
+        var _a, _b;
+        this.started = false;
+        this.stopped = false;
+        this.client = options.client;
+        this.repos = [...options.scope.repos];
+        this.permissions = options.scope.permissions;
+        this.logger = (_a = options.logger) !== null && _a !== void 0 ? _a : (() => { });
+        this.now = (_b = options.now) !== null && _b !== void 0 ? _b : (() => Date.now());
+    }
+    start() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.stopped) {
+                throw new Error("Cursor account GitHub credentials have been stopped.");
+            }
+            if (this.started) {
+                return;
+            }
+            this.previousGhToken = process.env.GH_TOKEN;
+            this.started = true;
+            try {
+                const token = yield this.getToken();
+                this.installGhToken(token);
+                this.scheduleRefresh();
+            }
+            catch (error) {
+                this.started = false;
+                this.restoreGhToken();
+                throw error;
+            }
+        });
+    }
+    getToken() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.stopped) {
+                throw new Error("Cursor account GitHub credentials have been stopped.");
+            }
+            const now = this.now();
+            if (this.cached !== undefined && now >= this.cached.expiresAtMs) {
+                // Expired leases must not be served; drop them so the next mint is clean.
+                this.cached = undefined;
+                this.restoreGhToken();
+            }
+            if (this.cached !== undefined && now < this.cached.refreshAtMs) {
+                return this.cached.token;
+            }
+            if (this.failure !== undefined && now < this.failure.retryAtMs && this.cached === undefined) {
+                throw new Error(this.failure.message);
+            }
+            if (this.refreshPromise === undefined) {
+                this.refreshPromise = this.refresh().finally(() => {
+                    this.refreshPromise = undefined;
+                });
+            }
+            return this.refreshPromise;
+        });
+    }
+    stop() {
+        this.started = false;
+        this.stopped = true;
+        if (this.refreshTimer !== undefined) {
+            clearTimeout(this.refreshTimer);
+            this.refreshTimer = undefined;
+        }
+        this.cached = undefined;
+        this.failure = undefined;
+        this.restoreGhToken();
+    }
+    refresh() {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const result = yield this.client.getGithubToken(this.repos, {
+                    permissions: this.permissions,
+                });
+                if (this.stopped) {
+                    throw new Error("Cursor account GitHub credentials have been stopped.");
+                }
+                const expiresAtMs = Date.parse(result.expiresAt);
+                if (!Number.isFinite(expiresAtMs) || expiresAtMs <= this.now() + REFRESH_LEEWAY_MS) {
+                    throw new Error("Cursor backend returned an invalid GitHub credential expiry.");
+                }
+                this.failure = undefined;
+                this.cached = {
+                    token: result.token,
+                    expiresAtMs,
+                    refreshAtMs: expiresAtMs - REFRESH_LEEWAY_MS,
+                };
+                if (this.started) {
+                    this.installGhToken(result.token);
+                    this.scheduleRefresh();
+                }
+                this.logger(`[agent-sdk] 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.cached.refreshAtMs = Math.min(this.cached.expiresAtMs, this.now() + REFRESH_RETRY_MS);
+                    if (this.started) {
+                        this.scheduleRetry();
+                    }
+                    return this.cached.token;
+                }
+                // Hard failure with no usable lease: evict any stale cache and back off.
+                this.cached = undefined;
+                this.restoreGhToken();
+                this.failure = {
+                    message,
+                    retryAtMs: this.now() + failureBackoffMs(error),
+                };
+                if (this.started) {
+                    this.scheduleRetry();
+                }
+                throw error instanceof Error ? error : new Error(message);
+            }
+        });
+    }
+    scheduleRefresh() {
+        if (!this.started || this.cached === undefined) {
+            return;
+        }
+        this.replaceTimer(Math.max(MIN_TIMER_DELAY_MS, this.cached.refreshAtMs - this.now()));
+    }
+    scheduleRetry() {
+        if (!this.started) {
+            return;
+        }
+        const delayMs = this.failure !== undefined
+            ? Math.max(MIN_TIMER_DELAY_MS, this.failure.retryAtMs - this.now())
+            : REFRESH_RETRY_MS;
+        this.replaceTimer(delayMs);
+    }
+    replaceTimer(delayMs) {
+        var _a, _b;
+        if (this.refreshTimer !== undefined) {
+            clearTimeout(this.refreshTimer);
+        }
+        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.scheduleRetry();
+            });
+        }, delayMs);
+        (_b = (_a = this.refreshTimer).unref) === null || _b === void 0 ? void 0 : _b.call(_a);
+    }
+    installGhToken(token) {
+        process.env.GH_TOKEN = token;
+        this.installedGhToken = token;
+    }
+    restoreGhToken() {
+        if (this.installedGhToken !== undefined && process.env.GH_TOKEN === this.installedGhToken) {
+            if (this.previousGhToken === undefined) {
+                delete process.env.GH_TOKEN;
+            }
+            else {
+                process.env.GH_TOKEN = this.previousGhToken;
+            }
+        }
+        this.installedGhToken = undefined;
+    }
+}
+function failureBackoffMs(error) {
+    if (error instanceof CursorBackendError && error.retryAfterMs !== undefined) {
+        return Math.min(Math.max(error.retryAfterMs, FAILURE_CACHE_TTL_MS), MAX_RETRY_AFTER_MS);
+    }
+    return FAILURE_CACHE_TTL_MS;
+}

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

@@ -0,0 +1,41 @@
+/**
+ * The hosted v2 per-request secret handoff: bind files in, `process.env` out,
+ * nothing recoverable left on disk.
+ *
+ * The control plane rewrites `/run/cursor/secrets/` before every hosted
+ * admission and execution because it cannot set the already-running July
+ * process's environment. This module closes that handoff at the top of each
+ * request: copy both documents into `process.env`, then destroy them. Hosted
+ * request code and authored agents read env from there on — nothing on the
+ * hosted path should open these paths again.
+ *
+ * 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.
+ */
+/** Wire error code for a bind file that outlived its consume. */
+export declare const BOUND_SECRETS_NOT_CONSUMED = "bound_secrets_not_consumed";
+export type HostedBoundSecretsResult = {
+    ok: true;
+} | {
+    ok: false;
+    code: typeof BOUND_SECRETS_NOT_CONSUMED;
+    message: string;
+};
+/**
+ * Hydrate `process.env` from both bind files and remove them from disk.
+ * Returns a failure when either secret is still readable afterwards.
+ *
+ * Both paths are platform constants, deliberately not the `CURSOR_API_KEY_FILE`
+ * override that {@link resolveApiKeySync} honors. That override is a read
+ * chain; this is a destructive consume. Following it here would let authored
+ * code redirect the destroy at a decoy path — reporting success while the real
+ * bind file stays live — and would delete an operator's own long-lived key
+ * file on a surface that points the variable at one.
+ */
+export declare function consumeHostedBoundSecrets(options?: {
+    apiKeyFilePath?: string;
+    deploymentSecretsFilePath?: string;
+}): HostedBoundSecretsResult;
+//# sourceMappingURL=hosted-bound-secrets.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,54 @@
+/**
+ * The hosted v2 per-request secret handoff: bind files in, `process.env` out,
+ * nothing recoverable left on disk.
+ *
+ * The control plane rewrites `/run/cursor/secrets/` before every hosted
+ * admission and execution because it cannot set the already-running July
+ * process's environment. This module closes that handoff at the top of each
+ * request: copy both documents into `process.env`, then destroy them. Hosted
+ * request code and authored agents read env from there on — nothing on the
+ * hosted path should open these paths again.
+ *
+ * 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.
+ */
+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";
+/**
+ * Hydrate `process.env` from both bind files and remove them from disk.
+ * Returns a failure when either secret is still readable afterwards.
+ *
+ * Both paths are platform constants, deliberately not the `CURSOR_API_KEY_FILE`
+ * override that {@link resolveApiKeySync} honors. That override is a read
+ * chain; this is a destructive consume. Following it here would let authored
+ * code redirect the destroy at a decoy path — reporting success while the real
+ * bind file stays live — and would delete an operator's own long-lived key
+ * file on a surface that points the variable at one.
+ */
+export function consumeHostedBoundSecrets(options) {
+    var _a, _b;
+    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);
+    if (secrets.disposal.state === "readable") {
+        survivors.push(`${secretsPath} (${secrets.disposal.reason})`);
+    }
+    const apiKeyPath = (_b = options === null || options === void 0 ? void 0 : options.apiKeyFilePath) !== null && _b !== void 0 ? _b : DEFAULT_CURSOR_API_KEY_FILE;
+    const apiKey = consumeBoundCursorApiKey({ filePath: apiKeyPath });
+    if (apiKey.disposal.state === "readable") {
+        survivors.push(`${apiKeyPath} (${apiKey.disposal.reason})`);
+    }
+    if (survivors.length === 0) {
+        return { ok: true };
+    }
+    return {
+        ok: false,
+        code: BOUND_SECRETS_NOT_CONSUMED,
+        message: `Task-bind secrets are still readable after being hydrated into the ` +
+            `environment, so authored work did not run: ${survivors.join(", ")}.`,
+    };
+}

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

@@ -0,0 +1,30 @@
+/**
+ * Task-time application secrets for hosted v2 freeze restores.
+ *
+ * The deployment host rewrites this tmpfs document before each admission and
+ * execution request. July reloads it synchronously because the process was
+ * already running in the frozen snapshot when the task-specific values
+ * arrived, then destroys the document: `process.env` is the source authored
+ * code reads, and the file is only how the value crossed the process
+ * boundary.
+ */
+import { type BoundSecretFileDisposal } from "./bound-secret-file.js";
+export declare const DEFAULT_AGENT_SERVE_DEPLOYMENT_SECRETS_FILE = "/run/cursor/secrets/AGENT_SERVE_DEPLOYMENT_SECRETS.json";
+export type BoundDeploymentSecretsConsumeResult = {
+    /** The document supplied values on this call. */
+    applied: boolean;
+    disposal: BoundSecretFileDisposal;
+};
+/**
+ * Apply the bound document to `process.env`, then destroy it.
+ *
+ * The env refresh always runs first, so a failed destroy never costs the
+ * request its secrets. A malformed document is destroyed too: it carries no
+ * values this process can use, and leaving it on disk only leaves whatever
+ * the control plane did manage to write.
+ *
+ * A `readable` disposal means the document survived; hosted callers must fail
+ * the request rather than run authored code next to a live secrets file.
+ */
+export declare function consumeBoundDeploymentSecrets(path?: string): BoundDeploymentSecretsConsumeResult;
+//# sourceMappingURL=hosted-deployment-secrets.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hosted-deployment-secrets.d.ts","sourceRoot":"","sources":["../../../src/internal/cursor/hosted-deployment-secrets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,EAAE,KAAK,uBAAuB,EAA0B,MAAM,wBAAwB,CAAC;AAE9F,eAAO,MAAM,2CAA2C,4DACG,CAAC;AAuD5D,MAAM,MAAM,mCAAmC,GAAG;IAChD,iDAAiD;IACjD,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,uBAAuB,CAAC;CACnC,CAAC;AAEF;;;;;;;;;;GAUG;AACH,wBAAgB,6BAA6B,CAC3C,IAAI,GAAE,MAAoD,GACzD,mCAAmC,CASrC"}

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

@@ -0,0 +1,81 @@
+/**
+ * Task-time application secrets for hosted v2 freeze restores.
+ *
+ * The deployment host rewrites this tmpfs document before each admission and
+ * execution request. July reloads it synchronously because the process was
+ * already running in the frozen snapshot when the task-specific values
+ * arrived, then destroys the document: `process.env` is the source authored
+ * code reads, and the file is only how the value crossed the process
+ * boundary.
+ */
+import { readFileSync } from "node:fs";
+import { destroyBoundSecretFile } from "./bound-secret-file.js";
+export const DEFAULT_AGENT_SERVE_DEPLOYMENT_SECRETS_FILE = "/run/cursor/secrets/AGENT_SERVE_DEPLOYMENT_SECRETS.json";
+const SECRET_NAME_PATTERN = /^[A-Z][A-Z0-9_]{0,63}$/;
+const appliedSecretNames = new Set();
+function parseBoundSecrets(path) {
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (_a) {
+        return undefined;
+    }
+    if (parsed === null || typeof parsed !== "object") {
+        return undefined;
+    }
+    const envelope = parsed;
+    if (envelope.v !== 1 ||
+        envelope.secrets === null ||
+        typeof envelope.secrets !== "object" ||
+        Array.isArray(envelope.secrets)) {
+        return undefined;
+    }
+    const secrets = {};
+    for (const [name, value] of Object.entries(envelope.secrets)) {
+        if (SECRET_NAME_PATTERN.test(name) &&
+            !name.startsWith("CURSOR_") &&
+            typeof value === "string") {
+            secrets[name] = value;
+        }
+    }
+    return secrets;
+}
+/**
+ * Apply the latest bound document to `process.env`. An empty valid document
+ * removes values loaded by an earlier bind after the deployment secret was
+ * unset, which is why the applied names are tracked across calls.
+ */
+function applyBoundSecrets(secrets) {
+    for (const name of appliedSecretNames) {
+        if (!(name in secrets)) {
+            delete process.env[name];
+        }
+    }
+    appliedSecretNames.clear();
+    for (const [name, value] of Object.entries(secrets)) {
+        process.env[name] = value;
+        appliedSecretNames.add(name);
+    }
+}
+/**
+ * Apply the bound document to `process.env`, then destroy it.
+ *
+ * The env refresh always runs first, so a failed destroy never costs the
+ * request its secrets. A malformed document is destroyed too: it carries no
+ * values this process can use, and leaving it on disk only leaves whatever
+ * the control plane did manage to write.
+ *
+ * A `readable` disposal means the document survived; hosted callers must fail
+ * the request rather than run authored code next to a live secrets file.
+ */
+export function consumeBoundDeploymentSecrets(path = DEFAULT_AGENT_SERVE_DEPLOYMENT_SECRETS_FILE) {
+    const secrets = parseBoundSecrets(path);
+    if (secrets !== undefined) {
+        applyBoundSecrets(secrets);
+    }
+    return {
+        applied: secrets !== undefined,
+        disposal: destroyBoundSecretFile(path),
+    };
+}

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

@@ -0,0 +1,63 @@
+/**
+ * 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}.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+export declare function storeProtocolEnablesStoreApi(protocol: string | undefined): boolean;
+/** Deployment user-land store: env, then task-bind file. */
+export declare function resolveDeploymentStoreSourceIdSync(env?: NodeJS.ProcessEnv): string | undefined;
+/** Engine framework store: env, then task-bind file. */
+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.
+ */
+export declare function resolveStoreProtocolSync(env?: NodeJS.ProcessEnv): string | undefined;
+export type CursorManagedV2StoreIds = {
+    deploymentStoreSourceId: string;
+    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.
+ */
+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

@@ -0,0 +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"}

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

@@ -0,0 +1,112 @@
+/**
+ * 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}.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+export function storeProtocolEnablesStoreApi(protocol) {
+    return protocol === AGENT_SERVE_FACTORY_API_PROTOCOL;
+}
+const STORE_SOURCE_ID_ENV = "AGENT_SERVE_STORE_SOURCE_ID";
+const FRAMEWORK_STORE_SOURCE_ID_ENV = "AGENT_SERVE_FRAMEWORK_STORE_SOURCE_ID";
+const STORE_SOURCE_ID_FILE_ENV = "AGENT_SERVE_STORE_SOURCE_ID_FILE";
+const FRAMEWORK_STORE_SOURCE_ID_FILE_ENV = "AGENT_SERVE_FRAMEWORK_STORE_SOURCE_ID_FILE";
+const STORE_PROTOCOL_ENV = "AGENT_SERVE_STORE_PROTOCOL";
+const STORE_PROTOCOL_FILE_ENV = "AGENT_SERVE_STORE_PROTOCOL_FILE";
+function readTrimmedFile(path) {
+    try {
+        const raw = readFileSync(path, "utf8").trim();
+        return raw === "" ? undefined : raw;
+    }
+    catch (_a) {
+        return undefined;
+    }
+}
+function readBoundSecretFile(fileEnvVar, defaultPath, env) {
+    var _a;
+    const configured = (_a = env[fileEnvVar]) === null || _a === void 0 ? void 0 : _a.trim();
+    const path = configured !== undefined && configured !== "" ? configured : defaultPath;
+    return readTrimmedFile(path);
+}
+/** Deployment user-land store: env, then task-bind file. */
+export function resolveDeploymentStoreSourceIdSync(env = process.env) {
+    var _a;
+    const fromEnv = (_a = env[STORE_SOURCE_ID_ENV]) === null || _a === void 0 ? void 0 : _a.trim();
+    if (fromEnv !== undefined && fromEnv !== "") {
+        return fromEnv;
+    }
+    return readBoundSecretFile(STORE_SOURCE_ID_FILE_ENV, DEFAULT_AGENT_SERVE_STORE_SOURCE_ID_FILE, env);
+}
+/** Engine framework store: env, then task-bind file. */
+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();
+    if (fromEnv !== undefined && fromEnv !== "") {
+        return fromEnv;
+    }
+    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.
+ */
+export function resolveStoreProtocolSync(env = process.env) {
+    var _a;
+    const fromEnv = (_a = env[STORE_PROTOCOL_ENV]) === null || _a === void 0 ? void 0 : _a.trim();
+    if (fromEnv !== undefined && fromEnv !== "") {
+        return fromEnv;
+    }
+    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.
+ */
+export function requireCursorManagedV2StoreIdsSync(env = process.env) {
+    const deploymentStoreSourceId = resolveDeploymentStoreSourceIdSync(env);
+    const frameworkStoreSourceId = resolveFrameworkStoreSourceIdSync(env);
+    if (deploymentStoreSourceId === undefined || frameworkStoreSourceId === undefined) {
+        throw new Error("Cursor-managed AgentSDK v2 requires AGENT_SERVE_STORE_SOURCE_ID and AGENT_SERVE_FRAMEWORK_STORE_SOURCE_ID");
+    }
+    return { deploymentStoreSourceId, frameworkStoreSourceId };
+}

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,CA+ClD"}