@cursor/bdk 0.2.3 → 0.2.5

package/src/storage-backends/cursor-hosted-v2.ts

@@ -1,204 +0,0 @@
-/**
- * Cursor-managed durable KV for hosted **architecture v2** agents.
- *
- * Talks to the AgentSDK v2 KV proxy
- * (`POST /internal/agentsdk/kv/*`) using the engine's pod
- * `CURSOR_API_KEY`. The server resolves the v2 deployment from that service
- * account (factorydb `agentsdk_deployment`) and persists rows in factorydb
- * `agentsdk_kv` — v1's Bugbot-backed `/internal/agent-serve/storage/*`
- * routes cannot resolve a v2 pod credential at all.
- *
- * The v2 wire protocol is four routes, not v1's eight:
- *
- * - `POST /internal/agentsdk/kv/get`
- *   `{ key }` → `{ found, value, version }` — reads always carry the CAS
- *   version token ({@link KvV2GetResponse}).
- * - `POST /internal/agentsdk/kv/put`
- *   `{ key, value, ifAbsent? | ifVersion? }` → `{ ok, version, current }`
- *   ({@link KvV2PutResponse}) — one write primitive: last-write-wins when
- *   unconditional (still bumps the token), atomic create-if-absent with
- *   `ifAbsent: true`, atomic compare-and-swap with `ifVersion`.
- * - `POST /internal/agentsdk/kv/delete` `{ key }` → `{ ok }`.
- * - `POST /internal/agentsdk/kv/list`
- *   `{ prefix, limit?, cursor?, keysOnly? }` → `{ entries, nextCursor }`
- *   ({@link KvV2ListResponse}) — ascending key order with keyset
- *   pagination. `list` / `listKeys` below drain every page, so the v1
- *   truncated-scan failure mode does not exist here.
- *
- * Eval runs still ride the v1 storage proxy's dedicated table (`evals`
- * below); moving them to factorydb is a separate follow-up from the KV
- * cutover.
- *
- * This backend is platform-selected for architecture v2
- * (framework-storage-selection.ts) — authors never import it; `agent/storage.ts`
- * is rejected on v2.
- */
-
-import type {
-  StorageCasTable,
-  StorageConfig,
-  StorageEntry,
-  StorageEvalsTable,
-} from "../storage.js";
-import type { JsonValue, KvCasResult, KvVersionedEntry } from "../types.js";
-import {
-  CURSOR_HOSTED_STORAGE,
-  type CursorHostedStorageOptions,
-  cursorHostedStorage,
-  storageRpc,
-} from "./cursor-hosted.js";
-
-const KV_V2_PREFIX = "/internal/agentsdk/kv";
-
-/** Wire shape of the v2 `get` route. `null` ⇒ JSON `undefined`. */
-export interface KvV2GetResponse {
-  found: boolean;
-  value: JsonValue | null;
-  version: string | null;
-}
-
-/** Wire shape of the v2 `put` route (all three write modes). */
-export interface KvV2PutResponse {
-  ok: boolean;
-  /** New version token on an accepted write, else `null`. */
-  version: string | null;
-  /** Entry observed when a conditional write lost; `null` when absent. */
-  current: { value: JsonValue | null; version: string } | null;
-}
-
-/** Wire shape of the v2 `list` route. */
-export interface KvV2ListResponse {
-  entries: Array<{
-    key: string;
-    /** Omitted when the request asked for keys only. */
-    value?: JsonValue | null;
-    version: string;
-  }>;
-  /** Last key of this page when more rows remain, else `null`. */
-  nextCursor: string | null;
-}
-
-type CursorHostedStorageV2Methods = Required<
-  Pick<StorageConfig, "put" | "get" | "delete" | "list">
-> & {
-  readonly [CURSOR_HOSTED_STORAGE]: true;
-  cas: StorageCasTable;
-  evals: StorageEvalsTable;
-};
-
-function toCasResult(response: KvV2PutResponse): KvCasResult {
-  if (response.ok) {
-    if (response.version === null) {
-      throw new Error("cursorHostedStorageV2: conditional write succeeded without a version token");
-    }
-    return { ok: true, version: response.version };
-  }
-  const current: KvVersionedEntry | undefined =
-    response.current === null
-      ? undefined
-      : {
-          value: response.current.value ?? null,
-          version: response.current.version,
-        };
-  return { ok: false, current };
-}
-
-/**
- * Drain every page of a v2 `list` scan. The server pages by keyset (each
- * `nextCursor` is the strictly-greatest key returned so far), so a cursor
- * that fails to advance means a broken server — fail loudly rather than
- * loop forever.
- */
-async function listAllPages(
-  options: CursorHostedStorageOptions,
-  body: { prefix: string; keysOnly?: boolean },
-): Promise<KvV2ListResponse["entries"]> {
-  const entries: KvV2ListResponse["entries"] = [];
-  let cursor: string | undefined;
-  for (;;) {
-    const page = await storageRpc<KvV2ListResponse>(
-      options,
-      `${KV_V2_PREFIX}/list`,
-      cursor === undefined ? body : { ...body, cursor },
-    );
-    entries.push(...page.entries);
-    if (page.nextCursor === null) {
-      return entries;
-    }
-    if (cursor !== undefined && page.nextCursor <= cursor) {
-      throw new Error(`cursorHostedStorageV2: list("${body.prefix}") cursor did not advance`);
-    }
-    cursor = page.nextCursor;
-  }
-}
-
-/**
- * Architecture-v2 `defineStorage` methods (AgentSDK v2 KV proxy → factorydb
- * `agentsdk_kv`). Platform-selected; spread into `defineStorage({...})` by
- * framework-storage-selection.ts. No `listNewest`: v2 session records live
- * on the framework file store, so the only consumer of write-time ordering
- * never reaches this backend and the engine's `list` fallback covers the
- * rest.
- */
-export function cursorHostedStorageV2(
-  options: CursorHostedStorageOptions = {},
-): CursorHostedStorageV2Methods {
-  // Eval runs stay on the v1 proxy's dedicated table.
-  const v1 = cursorHostedStorage(options);
-  return {
-    [CURSOR_HOSTED_STORAGE]: true,
-    async put(key, value): Promise<void> {
-      await storageRpc(options, `${KV_V2_PREFIX}/put`, { key, value });
-    },
-    async get(key): Promise<JsonValue | undefined> {
-      const result = await storageRpc<KvV2GetResponse>(options, `${KV_V2_PREFIX}/get`, { key });
-      if (!result.found) {
-        return undefined;
-      }
-      return result.value ?? undefined;
-    },
-    async delete(key): Promise<void> {
-      await storageRpc(options, `${KV_V2_PREFIX}/delete`, { key });
-    },
-    async list(prefix): Promise<StorageEntry[]> {
-      const entries = await listAllPages(options, { prefix });
-      return entries.map(entry => ({
-        key: entry.key,
-        value: entry.value ?? null,
-      }));
-    },
-    cas: {
-      async getWithVersion(key): Promise<KvVersionedEntry | undefined> {
-        const result = await storageRpc<KvV2GetResponse>(options, `${KV_V2_PREFIX}/get`, { key });
-        if (!result.found || result.version === null) {
-          return undefined;
-        }
-        return { value: result.value ?? null, version: result.version };
-      },
-      async putIfAbsent(key, value): Promise<KvCasResult> {
-        const result = await storageRpc<KvV2PutResponse>(options, `${KV_V2_PREFIX}/put`, {
-          key,
-          value,
-          ifAbsent: true,
-        });
-        return toCasResult(result);
-      },
-      async putIfVersion(key, value, expectedVersion): Promise<KvCasResult> {
-        const result = await storageRpc<KvV2PutResponse>(options, `${KV_V2_PREFIX}/put`, {
-          key,
-          value,
-          ifVersion: expectedVersion,
-        });
-        return toCasResult(result);
-      },
-      async listKeys(prefix): Promise<string[]> {
-        const entries = await listAllPages(options, {
-          prefix,
-          keysOnly: true,
-        });
-        return entries.map(entry => entry.key);
-      },
-    },
-    evals: v1.evals,
-  };
-}

package/src/storage-backends/cursor-hosted.ts

@@ -1,388 +0,0 @@
-/**
- * Cursor-managed durable storage for hosted agents.
- *
- * Talks to the control-plane storage proxy
- * (`POST /internal/agent-serve/storage/*`) using the engine's pod
- * `CURSOR_API_KEY`. The server resolves `deployment_id` from that service
- * account — engines never receive a Bugbot DSN and cannot address another
- * deployment's rows.
- *
- * On Cursor-managed hosting the start script pins `CURSOR_API_BASE_URL` to
- * `https://api.cursor.com` (where the proxy is mounted). Locally, point
- * `CURSOR_API_BASE_URL` at a backend that mounts Agent Serve routes and use
- * a deployment SA key, or use `@cursor/bdk/internal/file-kv` instead.
- * Wiring it into a storage sink is internal-only `defineStorage`
- * territory (see `storage.ts`).
- */
-
-import type { EvalRunSnapshot } from "../evals.js";
-import { injectActiveTraceContext } from "../otel.js";
-import type {
-  StorageCasTable,
-  StorageConfig,
-  StorageEntry,
-  StorageEvalsTable,
-} from "../storage.js";
-import type { JsonValue, KvCasResult, KvVersionedEntry } from "../types.js";
-
-/**
- * Same default as {@link cursorExternalApiUrl} in the CLI credentials module,
- * inlined here so this storage entrypoint does not import CLI/zod code.
- * Hosted monorepo examples load this file from `packages/agent-serve/src`
- * while `npm install` runs in the example package — a credentials import
- * would resolve `zod` from the wrong `node_modules` tree and crash serve.
- */
-const DEFAULT_CURSOR_EXTERNAL_API_URL = "https://api.cursor.com";
-
-/**
- * Diagnostic / self-host deployment id. Not the hosted-storage authz
- * boundary — the proxy scopes rows from the authenticated service account.
- */
-export const AGENT_SERVE_DEPLOYMENT_ID_ENV_VAR = "AGENT_SERVE_DEPLOYMENT_ID" as const;
-
-/**
- * Platform-managed secret / env names. User `secrets set` / DELETE cannot
- * claim these. Hosted storage talks to the HTTP proxy; engines never
- * receive a database URL.
- */
-export const CURSOR_HOSTED_STORAGE_ENV_VARS: readonly [typeof AGENT_SERVE_DEPLOYMENT_ID_ENV_VAR] = [
-  AGENT_SERVE_DEPLOYMENT_ID_ENV_VAR,
-];
-
-export interface CursorHostedStorageOptions {
-  /**
-   * Control-plane base URL (default: `CURSOR_API_BASE_URL`, else
-   * `https://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, so a value captured at construct time
-   * would be permanently absent. Used by the platform-selected v2
-   * defaults; kept separate so `apiKey` stays a plain string for authors.
-   */
-  resolveApiKey?: () => string | undefined;
-  /** Injected for tests. */
-  fetch?: typeof fetch;
-}
-
-/**
- * Marker stamped on {@link cursorHostedStorage} so the engine can prefer
- * durable Bugbot rows for `GET /v1/sessions` (survives `defineStorage` spread).
- * Explicit `unique symbol` annotation required for `--isolatedDeclarations`
- * (TS9010).
- */
-export const CURSOR_HOSTED_STORAGE: unique symbol = Symbol.for(
-  "@cursor/july.storage.cursor-hosted",
-);
-
-/** True when `value` is (or was built from) {@link cursorHostedStorage}. */
-export function isCursorHostedStorage(value: unknown): boolean {
-  return (
-    typeof value === "object" &&
-    value !== null &&
-    (value as Record<symbol, unknown>)[CURSOR_HOSTED_STORAGE] === true
-  );
-}
-
-type CursorHostedStorageMethods = Required<
-  Pick<StorageConfig, "put" | "get" | "delete" | "list" | "listNewest">
-> & {
-  readonly [CURSOR_HOSTED_STORAGE]: true;
-  cas: StorageCasTable;
-  evals: StorageEvalsTable;
-};
-
-// ============================================================================
-// CAS wire protocol
-// ============================================================================
-//
-// Served by the backend Agent Serve storage proxy
-// (`backend/server/src/agentServe/agentServeHostedStorage.ts`, routes in
-// `agentServeEndpoints.ts`) over `agent_serve_kv` and its `version BIGINT`
-// column. Each call is atomic server-side:
-//
-// - `POST /internal/agent-serve/storage/kv/get-with-version`
-//   `{ key }` → `{ found, value, version }` ({@link KvGetWithVersionResponse}).
-// - `POST /internal/agent-serve/storage/kv/put-if-absent`
-//   `{ key, value }` → `{ ok, version, current }` ({@link KvCasResponse});
-//   plain INSERT, unique-violation conflict returns the existing row as
-//   `current`.
-// - `POST /internal/agent-serve/storage/kv/put-if-version`
-//   `{ key, value, expectedVersion }` → `{ ok, version, current }`;
-//   one conditional `UPDATE … SET value, version = version + 1 WHERE key
-//   AND version = expected`, conflict returns the current row (or
-//   `current: null` when the row is gone).
-// - `POST /internal/agent-serve/storage/kv/list-keys`
-//   `{ prefix }` → `{ keys, truncated }` ({@link KvListKeysResponse}) in
-//   ascending key order (prefix scan on the `(deployment_id, key)`
-//   primary key). `truncated: true` means the scan hit the server's row
-//   cap and the list is incomplete; this client throws on it.
-
-/** Wire shape of the `get-with-version` route. `null` ⇒ JSON `undefined`. */
-export interface KvGetWithVersionResponse {
-  found: boolean;
-  value: JsonValue | null;
-  version: string | null;
-}
-
-/** Wire shape of the `put-if-absent` / `put-if-version` routes. */
-export interface KvCasResponse {
-  ok: boolean;
-  /** New version on success, else `null`. */
-  version: string | null;
-  /** Entry observed on conflict; `null` when the key is absent. */
-  current: { value: JsonValue | null; version: string } | null;
-}
-
-/** Wire shape of the `list-keys` route. */
-export interface KvListKeysResponse {
-  keys: string[];
-  /**
-   * Set when the scan hit the server's row cap and `keys` is incomplete.
-   * Additive: older servers omit it (treated as `false`).
-   */
-  truncated?: boolean;
-}
-
-const STORAGE_RPC_ERROR_CODES = new Set([
-  "agentsdk_kv_credential_missing",
-  "agentsdk_kv_cursor_invalid",
-  "agentsdk_kv_deployment_unbound",
-  "agentsdk_kv_key_invalid",
-  "agentsdk_kv_request_invalid",
-  "agentsdk_kv_storage_not_allowed",
-  "agentsdk_kv_value_invalid",
-  "agentsdk_kv_version_invalid",
-]);
-
-export class StorageRpcError extends Error {
-  readonly code = "agent_dependency_failed";
-  readonly reasonCode: string;
-  readonly status: number;
-
-  constructor(message: string, reasonCode: string, status: number) {
-    super(message);
-    this.name = "StorageRpcError";
-    this.reasonCode = reasonCode;
-    this.status = status;
-  }
-}
-
-function toCasResult(response: KvCasResponse): KvCasResult {
-  if (response.ok) {
-    if (response.version === null) {
-      throw new Error("cursorHostedStorage: CAS success without a version token");
-    }
-    return { ok: true, version: response.version };
-  }
-  const current: KvVersionedEntry | undefined =
-    response.current === null
-      ? undefined
-      : {
-          value: response.current.value ?? null,
-          version: response.current.version,
-        };
-  return { ok: false, current };
-}
-
-function resolveApiKey(options: CursorHostedStorageOptions): string {
-  const configured = options.resolveApiKey?.() ?? options.apiKey;
-  const key = (configured ?? process.env.CURSOR_API_KEY)?.trim();
-  if (key === undefined || key === "") {
-    throw new Error(
-      "cursorHostedStorage requires CURSOR_API_KEY (deployment pod credential on Cursor hosting)",
-    );
-  }
-  return key;
-}
-
-function resolveBaseUrl(options: CursorHostedStorageOptions): string {
-  const raw = (
-    options.baseUrl ??
-    process.env.CURSOR_API_BASE_URL ??
-    DEFAULT_CURSOR_EXTERNAL_API_URL
-  ).trim();
-  return raw.endsWith("/") ? raw.slice(0, -1) : raw;
-}
-
-/**
- * One authenticated POST to the control-plane proxy. Shared with the
- * architecture-v2 backend (`cursor-hosted-v2.ts`), which speaks a different
- * route family over the same transport and credential chain.
- */
-export async function storageRpc<T>(
-  options: CursorHostedStorageOptions,
-  path: string,
-  body: Record<string, unknown>,
-): Promise<T> {
-  const baseUrl = resolveBaseUrl(options);
-  const apiKey = resolveApiKey(options);
-  const fetchImpl = options.fetch ?? globalThis.fetch;
-  if (typeof fetchImpl !== "function") {
-    throw new Error("cursorHostedStorage requires fetch");
-  }
-  const headers = new Headers({
-    Authorization: `Bearer ${apiKey}`,
-    "Content-Type": "application/json",
-  });
-  injectActiveTraceContext(headers);
-  const response = await fetchImpl(`${baseUrl}${path}`, {
-    method: "POST",
-    headers,
-    body: JSON.stringify(body),
-  });
-  const text = await response.text();
-  let parsed: unknown;
-  try {
-    parsed = text.length === 0 ? {} : JSON.parse(text);
-  } catch {
-    throw new Error(`cursorHostedStorage ${path} returned non-JSON (${response.status})`);
-  }
-  if (!response.ok) {
-    const error =
-      parsed !== null &&
-      typeof parsed === "object" &&
-      "error" in parsed &&
-      typeof (parsed as { error: unknown }).error === "string"
-        ? (parsed as { error: string }).error
-        : `HTTP ${response.status}`;
-    const candidate =
-      parsed !== null &&
-      typeof parsed === "object" &&
-      "code" in parsed &&
-      typeof (parsed as { code: unknown }).code === "string"
-        ? (parsed as { code: string }).code
-        : undefined;
-    const code =
-      candidate !== undefined && STORAGE_RPC_ERROR_CODES.has(candidate)
-        ? candidate
-        : "agentsdk_storage_http_error";
-    throw new StorageRpcError(`cursorHostedStorage ${path}: ${error}`, code, response.status);
-  }
-  return parsed as T;
-}
-
-/**
- * Cursor-hosted `defineStorage` methods (control-plane storage proxy →
- * Bugbot `agent_serve_*` tables). Spread into `defineStorage({...})`.
- */
-export function cursorHostedStorage(
-  options: CursorHostedStorageOptions = {},
-): CursorHostedStorageMethods {
-  return {
-    [CURSOR_HOSTED_STORAGE]: true,
-    async put(key, value): Promise<void> {
-      await storageRpc(options, "/internal/agent-serve/storage/kv/put", {
-        key,
-        value,
-      });
-    },
-    async get(key): Promise<JsonValue | undefined> {
-      const result = await storageRpc<{
-        found: boolean;
-        value: JsonValue | null;
-      }>(options, "/internal/agent-serve/storage/kv/get", { key });
-      if (!result.found) {
-        return undefined;
-      }
-      return result.value ?? undefined;
-    },
-    async delete(key): Promise<void> {
-      await storageRpc(options, "/internal/agent-serve/storage/kv/delete", {
-        key,
-      });
-    },
-    async list(prefix): Promise<StorageEntry[]> {
-      const result = await storageRpc<{
-        entries: Array<{ key: string; value: JsonValue }>;
-      }>(options, "/internal/agent-serve/storage/kv/list", { prefix });
-      return result.entries;
-    },
-    async listNewest(prefix, limit): Promise<StorageEntry[]> {
-      // Same route; the server orders the prefix range by row write time
-      // and caps the rows instead of returning the whole range.
-      const result = await storageRpc<{
-        entries: Array<{ key: string; value: JsonValue }>;
-      }>(options, "/internal/agent-serve/storage/kv/list", {
-        prefix,
-        limit,
-        newestFirst: true,
-      });
-      return result.entries;
-    },
-    // Conditional writes over the same proxy (server routes: see the CAS
-    // wire-protocol block above). The proxy scopes rows from the service
-    // account, so ctx is not part of the wire contract.
-    cas: {
-      async getWithVersion(key): Promise<KvVersionedEntry | undefined> {
-        const result = await storageRpc<KvGetWithVersionResponse>(
-          options,
-          "/internal/agent-serve/storage/kv/get-with-version",
-          { key },
-        );
-        if (!result.found || result.version === null) {
-          return undefined;
-        }
-        return { value: result.value ?? null, version: result.version };
-      },
-      async putIfAbsent(key, value): Promise<KvCasResult> {
-        const result = await storageRpc<KvCasResponse>(
-          options,
-          "/internal/agent-serve/storage/kv/put-if-absent",
-          { key, value },
-        );
-        return toCasResult(result);
-      },
-      async putIfVersion(key, value, expectedVersion): Promise<KvCasResult> {
-        const result = await storageRpc<KvCasResponse>(
-          options,
-          "/internal/agent-serve/storage/kv/put-if-version",
-          { key, value, expectedVersion },
-        );
-        return toCasResult(result);
-      },
-      async listKeys(prefix): Promise<string[]> {
-        const result = await storageRpc<KvListKeysResponse>(
-          options,
-          "/internal/agent-serve/storage/kv/list-keys",
-          { prefix },
-        );
-        if (result.truncated === true) {
-          // Callers treat the result as the complete key set; a silently
-          // capped scan hides missing keys. Fail loudly until pagination
-          // lands.
-          throw new Error(
-            `cursorHostedStorage: listKeys("${prefix}") exceeded the server's row cap and was truncated; the result is incomplete`,
-          );
-        }
-        return result.keys;
-      },
-    },
-    evals: {
-      async put(run, ctx): Promise<void> {
-        await storageRpc(options, "/internal/agent-serve/storage/evals/put", {
-          agentName: ctx.agentName,
-          run,
-        });
-      },
-      async delete(runId, ctx): Promise<void> {
-        await storageRpc(options, "/internal/agent-serve/storage/evals/delete", {
-          agentName: ctx.agentName,
-          runId,
-        });
-      },
-      async list(ctx): Promise<EvalRunSnapshot[]> {
-        const result = await storageRpc<{ runs: EvalRunSnapshot[] }>(
-          options,
-          "/internal/agent-serve/storage/evals/list",
-          { agentName: ctx.agentName },
-        );
-        return result.runs;
-      },
-    },
-  };
-}