@cursor/bdk 0.2.3 → 0.2.5

package/src/internal/cursor/cursor-api-transport.ts

@@ -1,65 +0,0 @@
-/**
- * The one resolution of "which Cursor control plane, as whom" for hosted
- * transports. The verb-lane files sink (`files-backends/cursor-hosted.ts`)
- * and the domain-lane store API client (`store-api-client.ts`) both build on
- * these, so the pod credential and base URL resolve identically on every
- * wire — one place to change, no drift between lanes.
- */
-
-/**
- * Same default as the hosted storage backend, inlined so these entrypoints
- * do not import CLI code.
- */
-export const DEFAULT_CURSOR_EXTERNAL_API_URL = "https://api.cursor.com";
-
-export interface CursorApiTransportOptions {
-  /** Control-plane base URL (default: `CURSOR_API_BASE_URL`, else api.cursor.com). */
-  baseUrl?: string;
-  /** Bearer credential (default: `CURSOR_API_KEY`). */
-  apiKey?: string;
-  /**
-   * Lazy credential, re-resolved on every call and preferred over
-   * {@link apiKey} — hosted freeze snapshots listen unsigned and bind the
-   * key file after serve start. Kept separate so `apiKey` stays a plain
-   * string.
-   */
-  resolveApiKey?: () => string | undefined;
-  /** Test seam; defaults to global fetch. */
-  fetch?: typeof fetch;
-}
-
-function trimTrailingSlash(raw: string): string {
-  const trimmed = raw.trim();
-  return trimmed.endsWith("/") ? trimmed.slice(0, -1) : trimmed;
-}
-
-export function resolveCursorApiBaseUrl(options: CursorApiTransportOptions): string {
-  return trimTrailingSlash(
-    options.baseUrl ?? process.env.CURSOR_API_BASE_URL ?? DEFAULT_CURSOR_EXTERNAL_API_URL,
-  );
-}
-
-/**
- * The pod credential is the whole authorization on every hosted wire: the
- * API resolves the caller's deployment from it, so there is no second,
- * narrower credential to manage. Fails loudly rather than defaulting —
- * calling the control plane as nobody is worse than not calling.
- */
-export function resolveCursorApiKey(options: CursorApiTransportOptions): string {
-  const configured = options.resolveApiKey?.() ?? options.apiKey;
-  const key = (configured ?? process.env.CURSOR_API_KEY)?.trim();
-  if (key === undefined || key === "") {
-    throw new Error(
-      "Cursor hosted transport requires CURSOR_API_KEY (deployment pod credential on Cursor hosting)",
-    );
-  }
-  return key;
-}
-
-export function resolveCursorApiFetch(options: CursorApiTransportOptions): typeof fetch {
-  const impl = options.fetch ?? globalThis.fetch;
-  if (typeof impl !== "function") {
-    throw new Error("Cursor hosted transport requires fetch");
-  }
-  return impl;
-}

package/src/internal/cursor/github-credentials.ts

@@ -1,228 +0,0 @@
-/**
- * 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.
- */
-
-import type { CursorGithubRepoScope } from "../../channels/github/cursor-account.js";
-import type { CursorBackendClient } from "./backend-client.js";
-import { CursorBackendError } from "./backend-client.js";
-
-const REFRESH_LEEWAY_MS = 5 * 60_000;
-const REFRESH_RETRY_MS = 60_000;
-const FAILURE_CACHE_TTL_MS = 60_000;
-const MAX_RETRY_AFTER_MS = 60 * 60_000;
-const MIN_TIMER_DELAY_MS = 1_000;
-
-type GithubTokenClient = Pick<CursorBackendClient, "getGithubToken">;
-
-export interface CursorGithubCredentialProviderOptions {
-  client: GithubTokenClient;
-  scope: CursorGithubRepoScope;
-  logger?: (line: string) => void;
-  /** Test seam. */
-  now?: () => number;
-}
-
-interface CachedGithubToken {
-  token: string;
-  expiresAtMs: number;
-  refreshAtMs: number;
-}
-
-interface CachedFailure {
-  message: string;
-  retryAtMs: number;
-}
-
-export class CursorGithubCredentialProvider {
-  private readonly client: GithubTokenClient;
-  private readonly repos: string[];
-  private readonly permissions: CursorGithubRepoScope["permissions"];
-  private readonly logger: (line: string) => void;
-  private readonly now: () => number;
-  private cached: CachedGithubToken | undefined;
-  private failure: CachedFailure | undefined;
-  private refreshPromise: Promise<string> | undefined;
-  private refreshTimer: ReturnType<typeof setTimeout> | undefined;
-  private started = false;
-  private stopped = false;
-  private previousGhToken: string | undefined;
-  private installedGhToken: string | undefined;
-
-  constructor(options: CursorGithubCredentialProviderOptions) {
-    this.client = options.client;
-    this.repos = [...options.scope.repos];
-    this.permissions = options.scope.permissions;
-    this.logger = options.logger ?? (() => {});
-    this.now = options.now ?? (() => Date.now());
-  }
-
-  async start(): Promise<void> {
-    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 = await this.getToken();
-      this.installGhToken(token);
-      this.scheduleRefresh();
-    } catch (error) {
-      this.started = false;
-      this.restoreGhToken();
-      throw error;
-    }
-  }
-
-  async getToken(): Promise<string> {
-    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(): void {
-    this.started = false;
-    this.stopped = true;
-    if (this.refreshTimer !== undefined) {
-      clearTimeout(this.refreshTimer);
-      this.refreshTimer = undefined;
-    }
-    this.cached = undefined;
-    this.failure = undefined;
-    this.restoreGhToken();
-  }
-
-  private async refresh(): Promise<string> {
-    try {
-      const result = await 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);
-    }
-  }
-
-  private scheduleRefresh(): void {
-    if (!this.started || this.cached === undefined) {
-      return;
-    }
-    this.replaceTimer(Math.max(MIN_TIMER_DELAY_MS, this.cached.refreshAtMs - this.now()));
-  }
-
-  private scheduleRetry(): void {
-    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);
-  }
-
-  private replaceTimer(delayMs: number): void {
-    if (this.refreshTimer !== undefined) {
-      clearTimeout(this.refreshTimer);
-    }
-    this.refreshTimer = setTimeout(() => {
-      void this.getToken().catch((error: unknown) => {
-        this.logger(
-          `[agent-sdk] GitHub auth: Cursor account credential refresh failed: ${
-            error instanceof Error ? error.message : String(error)
-          }`,
-        );
-        this.scheduleRetry();
-      });
-    }, delayMs);
-    this.refreshTimer.unref?.();
-  }
-
-  private installGhToken(token: string): void {
-    process.env.GH_TOKEN = token;
-    this.installedGhToken = token;
-  }
-
-  private restoreGhToken(): void {
-    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: unknown): number {
-  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/src/internal/cursor/hosted-bound-secrets.ts

@@ -1,71 +0,0 @@
-/**
- * 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";
-
-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 function consumeHostedBoundSecrets(options?: {
-  apiKeyFilePath?: string;
-  deploymentSecretsFilePath?: string;
-}): HostedBoundSecretsResult {
-  const survivors: string[] = [];
-
-  const secretsPath =
-    options?.deploymentSecretsFilePath ?? DEFAULT_AGENT_SERVE_DEPLOYMENT_SECRETS_FILE;
-  const secrets = consumeBoundDeploymentSecrets(secretsPath);
-  if (secrets.disposal.state === "readable") {
-    survivors.push(`${secretsPath} (${secrets.disposal.reason})`);
-  }
-
-  const apiKeyPath = options?.apiKeyFilePath ?? 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/src/internal/cursor/hosted-deployment-secrets.ts

@@ -1,100 +0,0 @@
-/**
- * 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 { type BoundSecretFileDisposal, 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<string>();
-
-function parseBoundSecrets(path: string): Record<string, string> | undefined {
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(readFileSync(path, "utf8"));
-  } catch {
-    return undefined;
-  }
-  if (parsed === null || typeof parsed !== "object") {
-    return undefined;
-  }
-  const envelope = parsed as { v?: unknown; secrets?: unknown };
-  if (
-    envelope.v !== 1 ||
-    envelope.secrets === null ||
-    typeof envelope.secrets !== "object" ||
-    Array.isArray(envelope.secrets)
-  ) {
-    return undefined;
-  }
-  const secrets: Record<string, string> = {};
-  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: Record<string, string>): void {
-  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);
-  }
-}
-
-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 function consumeBoundDeploymentSecrets(
-  path: string = DEFAULT_AGENT_SERVE_DEPLOYMENT_SECRETS_FILE,
-): BoundDeploymentSecretsConsumeResult {
-  const secrets = parseBoundSecrets(path);
-  if (secrets !== undefined) {
-    applyBoundSecrets(secrets);
-  }
-  return {
-    applied: secrets !== undefined,
-    disposal: destroyBoundSecretFile(path),
-  };
-}

package/src/internal/cursor/hosted-store-secrets.ts

@@ -1,152 +0,0 @@
-/**
- * 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: string | undefined): boolean {
-  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: string | undefined): boolean {
-  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: string): string | undefined {
-  try {
-    const raw = readFileSync(path, "utf8").trim();
-    return raw === "" ? undefined : raw;
-  } catch {
-    return undefined;
-  }
-}
-
-function readBoundSecretFile(
-  fileEnvVar: string,
-  defaultPath: string,
-  env: NodeJS.ProcessEnv,
-): string | undefined {
-  const configured = env[fileEnvVar]?.trim();
-  const path = configured !== undefined && configured !== "" ? configured : defaultPath;
-  return readTrimmedFile(path);
-}
-
-/** Deployment user-land store: env, then task-bind file. */
-export function resolveDeploymentStoreSourceIdSync(
-  env: NodeJS.ProcessEnv = process.env,
-): string | undefined {
-  const fromEnv = env[STORE_SOURCE_ID_ENV]?.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: NodeJS.ProcessEnv = process.env,
-): string | undefined {
-  const fromEnv = env[FRAMEWORK_STORE_SOURCE_ID_ENV]?.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: NodeJS.ProcessEnv = process.env): string | undefined {
-  const fromEnv = env[STORE_PROTOCOL_ENV]?.trim();
-  if (fromEnv !== undefined && fromEnv !== "") {
-    return fromEnv;
-  }
-  return readBoundSecretFile(STORE_PROTOCOL_FILE_ENV, DEFAULT_AGENT_SERVE_STORE_PROTOCOL_FILE, env);
-}
-
-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 function requireCursorManagedV2StoreIdsSync(
-  env: NodeJS.ProcessEnv = process.env,
-): CursorManagedV2StoreIds {
-  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 };
-}