@cursor/bdk 0.2.2 → 0.2.4

package/src/internal/cursor/session-token.ts

@@ -1,111 +0,0 @@
-/**
- * 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 const CURSOR_SESSION_EXCHANGE_PATH = "/auth/exchange_user_api_key";
-/** Re-exchange when the cached session is within this window of expiry. */
-export const SESSION_TOKEN_EXPIRY_LEEWAY_MS: number = 5 * 60 * 1000;
-/** Fallback session lifetime when the JWT `exp` claim cannot be parsed. */
-export const SESSION_TOKEN_FALLBACK_LIFETIME_MS: number = 30 * 60 * 1000;
-const EXCHANGE_TIMEOUT_MS = 30_000;
-
-/**
- * Exchange failure. `status` is the HTTP status when the backend answered,
- * and undefined for network/transport errors. `detail` carries the server's
- * `error` field when present so callers can surface the reason verbatim.
- */
-export class CursorSessionExchangeError extends Error {
-  constructor(
-    message: string,
-    readonly status?: number,
-    readonly detail?: string,
-  ) {
-    super(message);
-    this.name = "CursorSessionExchangeError";
-  }
-}
-
-/** Epoch-ms expiry from a JWT `exp` claim, or undefined when unparsable. */
-export function jwtExpiryMs(token: string): number | undefined {
-  try {
-    const payload = token.split(".")[1];
-    if (payload === undefined) {
-      return undefined;
-    }
-    const claims = JSON.parse(Buffer.from(payload, "base64url").toString("utf8")) as {
-      exp?: unknown;
-    };
-    return typeof claims.exp === "number" ? claims.exp * 1000 : undefined;
-  } catch {
-    return undefined;
-  }
-}
-
-/**
- * One exchange round trip. Throws {@link CursorSessionExchangeError} on
- * transport failure, a non-2xx response, or a token-free body. `expiresAtMs`
- * comes from the session JWT's `exp` claim, falling back to
- * {@link SESSION_TOKEN_FALLBACK_LIFETIME_MS} for opaque tokens.
- */
-export async 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 }> {
-  const fetchImpl = args.fetchImpl ?? fetch;
-  let response: Response;
-  try {
-    response = await fetchImpl(args.exchangeUrl, {
-      method: "POST",
-      headers: {
-        "content-type": "application/json",
-        authorization: `Bearer ${args.apiKey}`,
-      },
-      body: "{}",
-      signal: AbortSignal.timeout(EXCHANGE_TIMEOUT_MS),
-    });
-  } catch (error) {
-    throw new CursorSessionExchangeError(
-      `Could not reach the Cursor session exchange at ${args.exchangeUrl}: ${
-        error instanceof Error ? error.message : String(error)
-      }`,
-    );
-  }
-  const body: unknown = await response.json().catch(() => undefined);
-  const record =
-    typeof body === "object" && body !== null && !Array.isArray(body)
-      ? (body as Record<string, unknown>)
-      : {};
-  const detail = typeof record.error === "string" && record.error !== "" ? record.error : undefined;
-  if (!response.ok) {
-    throw new CursorSessionExchangeError(
-      `Cursor session exchange failed with HTTP ${response.status}${
-        detail === undefined ? "" : ` (${detail})`
-      }.`,
-      response.status,
-      detail,
-    );
-  }
-  const token = record.accessToken;
-  if (typeof token !== "string" || token === "") {
-    throw new CursorSessionExchangeError(
-      "Cursor session exchange returned no access token.",
-      response.status,
-    );
-  }
-  const nowMs = args.nowMs ?? Date.now();
-  return {
-    token,
-    expiresAtMs: jwtExpiryMs(token) ?? nowMs + SESSION_TOKEN_FALLBACK_LIFETIME_MS,
-  };
-}

package/src/internal/cursor/store-api-client.ts

@@ -1,323 +0,0 @@
-/**
- * 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.
- *
- * 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.
- */
-
-import {
-  MEMORY_APPEND_MAX_RECORD_BYTES,
-  memoryAppendResponseSchema,
-  memoryReadResponseSchema,
-  STORE_API_MEMORY_APPEND_CALL,
-  STORE_API_MEMORY_READ_CALL,
-  STORE_API_PATH,
-  STORE_API_PROTOCOL_VERSION,
-  serializedRecordBytes,
-} from "../store-api-protocol.js";
-import {
-  type CursorApiTransportOptions,
-  resolveCursorApiBaseUrl,
-  resolveCursorApiFetch,
-  resolveCursorApiKey,
-} from "./cursor-api-transport.js";
-import {
-  resolveDeploymentStoreSourceIdSync,
-  resolveStoreProtocolSync,
-  storeProtocolEnablesStoreApi,
-} from "./hosted-store-secrets.js";
-
-export interface StoreApiClientOptions extends CursorApiTransportOptions {
-  /** Deployment store source id override (lane availability check). */
-  storeSourceId?: string;
-  /** Lazy store source id, preferred over {@link storeSourceId}. */
-  resolveStoreSourceId?: () => string | undefined;
-  /** Lazy store protocol pin (default: env, then the task-bound file). */
-  resolveStoreProtocol?: () => string | undefined;
-  /** Backoff sleep override (tests). */
-  sleep?: (ms: number) => Promise<void>;
-  /** Jitter source override (tests). Returns [0, 1). */
-  random?: () => number;
-}
-
-/**
- * How one domain call failed, after the client's bounded retries:
- *
- * - `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
- *   bound.
- * - `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";
-
-export class StoreApiCallError extends Error {
-  constructor(
-    readonly kind: StoreApiFailureKind,
-    message: string,
-    readonly status?: number,
-  ) {
-    super(message);
-    this.name = "StoreApiCallError";
-  }
-}
-
-/**
- * Bounded backoff policy. Domain calls run at turn boundaries (a memory
- * append after `turn.completed`), so the budget is a few short retries, not
- * persistence: 3 attempts total and never more than 2s asleep between them.
- * A 429 whose Retry-After exceeds the cap is a deliberate shed (a kill
- * switch, a hard budget) — give up immediately instead of camping on it.
- */
-const STORE_API_MAX_ATTEMPTS = 3;
-const STORE_API_MAX_BACKOFF_MS = 2_000;
-
-/**
- * Hard deadline per fetch (the envelope POSTs and the presigned journal
- * GET). Without one, a stalled — not failed — connection rides undici's
- * ~300 s inactivity timers, and hydration runs at the head of the session
- * dispatch chain where a stall delays every queued handler. 15 s matches
- * the server's own presigned-fetch deadline and is generous for a ≤5 MiB
- * journal.
- */
-const STORE_API_FETCH_TIMEOUT_MS = 15_000;
-
-function backoffMs(attempt: number, random: () => number): number {
-  return Math.min(200 * 2 ** attempt * (0.5 + random()), STORE_API_MAX_BACKOFF_MS);
-}
-
-/**
- * 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.
- */
-export function isStoreApiLaneEnabled(options: StoreApiClientOptions = {}): boolean {
-  const protocol = options.resolveStoreProtocol?.() ?? resolveStoreProtocolSync();
-  if (!storeProtocolEnablesStoreApi(protocol)) {
-    return false;
-  }
-  const sourceId = (
-    options.resolveStoreSourceId?.() ??
-    options.storeSourceId ??
-    resolveDeploymentStoreSourceIdSync()
-  )?.trim();
-  return sourceId !== undefined && sourceId !== "";
-}
-
-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).
-   */
-  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).
-   */
-  memoryReadContent(payload: { agent: string }): Promise<Uint8Array | undefined>;
-};
-
-export function createStoreApiClient(options: StoreApiClientOptions = {}): StoreApiClient {
-  const sleep =
-    options.sleep ?? ((ms: number) => new Promise<void>(resolve => setTimeout(resolve, ms)));
-  const random = options.random ?? Math.random;
-
-  /** One POST of a versioned envelope; returns the parsed 2xx body. */
-  const postOnce = async (call: string, envelope: Record<string, unknown>): Promise<Response> => {
-    const fetchImpl = resolveCursorApiFetch(options);
-    return await fetchImpl(`${resolveCursorApiBaseUrl(options)}${STORE_API_PATH}/${call}`, {
-      method: "POST",
-      headers: {
-        Authorization: `Bearer ${resolveCursorApiKey(options)}`,
-        "Content-Type": "application/json",
-      },
-      body: JSON.stringify(envelope),
-      signal: AbortSignal.timeout(STORE_API_FETCH_TIMEOUT_MS),
-    });
-  };
-
-  /** The response's `Retry-After` in ms, when present and numeric. */
-  const retryAfterDelayMs = (response: Response): number | undefined => {
-    const header = response.headers.get("retry-after")?.trim();
-    const seconds = header === undefined || header === "" ? Number.NaN : Number(header);
-    return Number.isFinite(seconds) ? seconds * 1_000 : undefined;
-  };
-
-  const describeErrorBody = async (response: Response): Promise<string> => {
-    try {
-      const parsed = (await response.json()) as { error?: unknown };
-      if (typeof parsed?.error === "string") {
-        return parsed.error;
-      }
-    } catch {
-      // Non-JSON error body; the status is the message.
-    }
-    return `HTTP ${response.status}`;
-  };
-
-  const callApi = async (call: string, envelope: Record<string, unknown>): Promise<unknown> => {
-    let lastFailure: StoreApiCallError | undefined;
-    // A shed's Retry-After (when within the cap) overrides the next jittered
-    // backoff; cleared before every attempt.
-    let nextDelayMs: number | undefined;
-    for (let attempt = 0; attempt < STORE_API_MAX_ATTEMPTS; attempt += 1) {
-      if (attempt > 0) {
-        await sleep(nextDelayMs ?? backoffMs(attempt, random));
-      }
-      nextDelayMs = undefined;
-      let response: Response;
-      try {
-        response = await postOnce(call, envelope);
-      } catch (error) {
-        lastFailure = new StoreApiCallError(
-          "unavailable",
-          `store api ${call} transport failure: ${
-            error instanceof Error ? error.message : String(error)
-          }`,
-        );
-        continue;
-      }
-      if (response.ok) {
-        try {
-          return (await response.json()) as unknown;
-        } catch {
-          throw new StoreApiCallError(
-            "bad_response",
-            `store api ${call} answered non-JSON (${response.status})`,
-            response.status,
-          );
-        }
-      }
-      if (response.status === 429) {
-        const retryDelayMs = retryAfterDelayMs(response);
-        const shed = new StoreApiCallError(
-          "shed",
-          `store api ${call} shed: ${await describeErrorBody(response)}`,
-          response.status,
-        );
-        if (retryDelayMs !== undefined && retryDelayMs > STORE_API_MAX_BACKOFF_MS) {
-          // A long Retry-After is a kill switch or hard budget: obey it by
-          // giving up now, not by camping on the route.
-          throw shed;
-        }
-        nextDelayMs = retryDelayMs;
-        lastFailure = shed;
-        continue;
-      }
-      if (response.status >= 500) {
-        // A degraded 503 carries `Retry-After` too (the server's buffer-down
-        // answer). Honor it clamped to the backoff cap — unlike a shed, a
-        // 5xx is transient by definition, so a long hint never means "give
-        // up", just "wait the cap".
-        const retryDelayMs = retryAfterDelayMs(response);
-        if (retryDelayMs !== undefined) {
-          nextDelayMs = Math.min(retryDelayMs, STORE_API_MAX_BACKOFF_MS);
-        }
-        lastFailure = new StoreApiCallError(
-          "unavailable",
-          `store api ${call} failed: ${await describeErrorBody(response)}`,
-          response.status,
-        );
-        continue;
-      }
-      // Any other 4xx is deterministic; retrying re-sends the same refusal.
-      throw new StoreApiCallError(
-        "rejected",
-        `store api ${call} rejected: ${await describeErrorBody(response)}`,
-        response.status,
-      );
-    }
-    throw lastFailure ?? new StoreApiCallError("unavailable", "no attempt ran");
-  };
-
-  return {
-    async memoryAppend(payload) {
-      const recordBytes = serializedRecordBytes(payload.record);
-      if (recordBytes > MEMORY_APPEND_MAX_RECORD_BYTES) {
-        // The server-side controller enforces the same cap; checking here
-        // spares a doomed request and fails with the same typed shape.
-        throw new StoreApiCallError(
-          "rejected",
-          `memory.append record is ${recordBytes} serialized bytes; the cap is ${MEMORY_APPEND_MAX_RECORD_BYTES}`,
-        );
-      }
-      const body = await callApi(STORE_API_MEMORY_APPEND_CALL, {
-        v: STORE_API_PROTOCOL_VERSION,
-        call: STORE_API_MEMORY_APPEND_CALL,
-        payload,
-      });
-      if (!memoryAppendResponseSchema.safeParse(body).success) {
-        throw new StoreApiCallError("bad_response", "unexpected memory.append response shape");
-      }
-    },
-
-    async memoryReadContent(payload) {
-      const body = await callApi(STORE_API_MEMORY_READ_CALL, {
-        v: STORE_API_PROTOCOL_VERSION,
-        call: STORE_API_MEMORY_READ_CALL,
-        payload,
-      });
-      const parsed = memoryReadResponseSchema.safeParse(body);
-      if (!parsed.success) {
-        throw new StoreApiCallError("bad_response", "unexpected memory.read response shape");
-      }
-      if (parsed.data.journal === null) {
-        return undefined;
-      }
-      // Bulk bytes ride the presigned URL, never the control plane — same
-      // split as the verb lane. Unretried: the whole call reruns at the
-      // next session start, and hydration keeps the existing mirror.
-      const fetchImpl = resolveCursorApiFetch(options);
-      let response: Response;
-      try {
-        response = await fetchImpl(parsed.data.journal.url, {
-          method: "GET",
-          redirect: "manual",
-          signal: AbortSignal.timeout(STORE_API_FETCH_TIMEOUT_MS),
-        });
-      } catch (error) {
-        throw new StoreApiCallError(
-          "unavailable",
-          `memory.read journal fetch transport failure: ${
-            error instanceof Error ? error.message : String(error)
-          }`,
-        );
-      }
-      if (response.status === 404) {
-        // The presign raced a rotation or delete; absent is absent.
-        return undefined;
-      }
-      if (!response.ok) {
-        throw new StoreApiCallError(
-          "unavailable",
-          `memory.read journal fetch failed (HTTP ${response.status})`,
-          response.status,
-        );
-      }
-      return new Uint8Array(await response.arrayBuffer());
-    },
-  };
-}