@cursor/bdk 0.2.3 → 0.2.4

package/src/internal/framework-file-storage.ts

@@ -1,357 +0,0 @@
-/**
- * Framework-level file storage for v2 hosted engines.
- *
- * Hosted deployments carry two file stores with different audiences:
- *
- * - the **user-level** store (`AGENT_SERVE_STORE_SOURCE_ID`) holds
- *   author-facing bytes — `ctx.host.files`, skills, memory, artifacts — and
- *   is browsable from the dashboard and mountable on cloud-runtime VMs;
- * - the **framework-level** store (`AGENT_SERVE_FRAMEWORK_STORE_SOURCE_ID`)
- *   holds engine-owned session state — session records, event transcripts,
- *   hosted-execution run logs, the continuation index, and the SDK
- *   conversation mirror — and is never mounted into author code or models.
- *   The authenticated dashboard may read diagnostic families, but never the
- *   continuation index.
- *
- * This module puts framework session state on the framework store. The
- * {@link storageKeys} scheme was designed for exactly this: keys are a
- * stable versioned contract that sinks may route on, so
- * {@link composeFrameworkStorage} splits one {@link StorageConfig} by key
- * kind — `session` / `session-events` / `session-runs` / `logs` /
- * `continuation` go to the framework file store (file-shaped; the store
- * accepts values up to 64 MiB per
- * object without chunking, versus the KV proxy's 1 MiB row cap), while
- * author `kv`, eval runs, and conditional writes stay on the control-plane
- * KV proxy (the dashboard reads them there, and CAS needs a database).
- *
- * v2 only, by construction: the composite is selected in
- * framework-storage-selection.ts, which v1 never reaches with a
- * platform-selected definition.
- */
-
-import type { FileSink } from "../files.js";
-import type { StorageConfig, StorageEntry } from "../storage.js";
-import { AGENTSDK_STORAGE_KEY_ROOT } from "../storage-protocol.js";
-import type { JsonValue } from "../types.js";
-import { mapBounded } from "./bounded.js";
-
-/**
- * Key kinds (`agentsdk/v1/{agent}/{kind}/…`) that live on the framework
- * file store. Everything else stays on the KV sink.
- */
-const FRAMEWORK_FILE_KINDS: ReadonlySet<string> = new Set([
-  "session",
-  "session-events",
-  "session-runs",
-  "logs",
-  "continuation",
-]);
-
-/**
- * Whether a framework-minted key (or list prefix) belongs on the framework
- * file store. Prefixes used by the coordinator are always at least
- * kind-scoped (`…/{agent}/session/`), so a prefix routes wholly to one side.
- */
-export function isFrameworkFileKey(key: string): boolean {
-  if (!key.startsWith(`${AGENTSDK_STORAGE_KEY_ROOT}/`)) {
-    return false;
-  }
-  const rest = key.slice(AGENTSDK_STORAGE_KEY_ROOT.length + 1);
-  const agentEnd = rest.indexOf("/");
-  if (agentEnd === -1) {
-    return false;
-  }
-  const afterAgent = rest.slice(agentEnd + 1);
-  const kindEnd = afterAgent.indexOf("/");
-  const kind = kindEnd === -1 ? afterAgent : afterAgent.slice(0, kindEnd);
-  return FRAMEWORK_FILE_KINDS.has(kind);
-}
-
-/**
- * The KV core over a {@link FileSink}: one JSON document per key.
- * `putMany` stays optional — the KV-proxy core has no batch write, and the
- * composite falls back to sequential puts on a side without one.
- */
-export type FileSinkStorageCore = Required<Pick<StorageConfig, "put" | "get" | "delete" | "list">> &
-  Pick<StorageConfig, "putMany">;
-
-/** Parallel per-key reads backing `list` (each is presign + object GET). */
-const LIST_READ_CONCURRENCY = 8;
-
-/**
- * A storage key whose path the file store cannot represent (an empty, `.`,
- * or `..` segment — possible only through caller-controlled segments such
- * as continuation tokens or a caller-supplied session id). Such an object
- * can never exist in the store, so reads are a definitive miss rather than
- * a per-request 400 that the lazy-restore path would propagate forever.
- */
-function isUnrepresentableFileKey(key: string): boolean {
-  return key.split("/").some(segment => segment === "" || segment === "." || segment === "..");
-}
-
-/**
- * Adapt a {@link FileSink} to the `defineStorage` KV core. Storage keys are
- * framework-minted (URI-encoded, length-bounded segments — see
- * {@link storageKeys}), so they are used as file keys verbatim; values are
- * stored as JSON bytes. Parse failures throw: on the lazy-restore path a
- * corrupt document must fail the follow-up rather than read as a miss, and
- * the startup bulk restore already logs-and-skips a throwing `list`.
- */
-export function fileSinkStorageCore(sink: FileSink): FileSinkStorageCore {
-  return {
-    async put(key, value): Promise<void> {
-      if (isUnrepresentableFileKey(key)) {
-        // Loud rather than silent: the coordinator logs and drops failed
-        // mirror writes (at-most-once), and awaited callers must not
-        // believe an impossible write landed.
-        throw new Error(
-          `framework file storage: key "${key}" has a path segment the store cannot represent`,
-        );
-      }
-      await sink.put(key, encodeDocument(key, value));
-    },
-    async putMany(entries): Promise<Array<{ key: string; error?: unknown }>> {
-      const results: Array<{ key: string; error?: unknown }> = entries.map(entry => ({
-        key: entry.key,
-      }));
-      const writable: Array<{ index: number; key: string; body: Uint8Array }> = [];
-      for (let index = 0; index < entries.length; index += 1) {
-        const entry = entries[index];
-        if (entry === undefined) {
-          continue;
-        }
-        if (isUnrepresentableFileKey(entry.key)) {
-          results[index] = {
-            key: entry.key,
-            error: new Error(
-              `framework file storage: key "${entry.key}" has a path segment the store cannot represent`,
-            ),
-          };
-          continue;
-        }
-        writable.push({
-          index,
-          key: entry.key,
-          body: encodeDocument(entry.key, entry.value),
-        });
-      }
-      if (writable.length === 0) {
-        return results;
-      }
-      if (sink.putMany !== undefined) {
-        // The point of the batch: one backend round trip for the flush.
-        const settled = await sink.putMany(writable.map(({ key, body }) => ({ key, body })));
-        for (let i = 0; i < writable.length; i += 1) {
-          const target = writable[i];
-          const outcome = settled[i];
-          if (target === undefined) {
-            continue;
-          }
-          if (outcome?.status === "rejected") {
-            results[target.index] = { key: target.key, error: outcome.reason };
-          }
-        }
-        return results;
-      }
-      // No batch support: sequential puts, preserving the sink's strict
-      // one-at-a-time ordering contract.
-      for (const target of writable) {
-        try {
-          await sink.put(target.key, target.body);
-        } catch (error) {
-          results[target.index] = { key: target.key, error };
-        }
-      }
-      return results;
-    },
-    async get(key): Promise<JsonValue | undefined> {
-      if (isUnrepresentableFileKey(key)) {
-        return undefined;
-      }
-      const body = await sink.get(key);
-      if (body === undefined) {
-        return undefined;
-      }
-      return decodeDocument(key, body instanceof Uint8Array ? body : body.body);
-    },
-    async delete(key): Promise<void> {
-      if (isUnrepresentableFileKey(key)) {
-        return;
-      }
-      await sink.delete(key);
-    },
-    async list(prefix): Promise<StorageEntry[]> {
-      const entries = await sink.list(prefix);
-      // FileSink.list returns metadata only, so the values are their own
-      // reads. Prefer the sink's batched read — on the hosted sink that is
-      // one control-plane call per 100 keys instead of one per key, which is
-      // what keeps a big restore under the store's per-deployment rate
-      // budget — and fall back to bounded per-key gets elsewhere.
-      const bodies =
-        sink.getMany !== undefined
-          ? await sink.getMany(entries.map(entry => entry.key))
-          : await mapBounded(entries, LIST_READ_CONCURRENCY, entry => sink.get(entry.key));
-      const out: StorageEntry[] = [];
-      for (let index = 0; index < entries.length; index += 1) {
-        const entry = entries[index];
-        const body = bodies[index];
-        if (entry === undefined || body === undefined) {
-          // Deleted between list and read; a miss is not corruption.
-          continue;
-        }
-        out.push({
-          key: entry.key,
-          value: decodeDocument(entry.key, body instanceof Uint8Array ? body : body.body),
-        });
-      }
-      return out;
-    },
-  };
-}
-
-function frameworkFileKind(key: string): string | undefined {
-  if (!key.startsWith(`${AGENTSDK_STORAGE_KEY_ROOT}/`)) {
-    return undefined;
-  }
-  const rest = key.slice(AGENTSDK_STORAGE_KEY_ROOT.length + 1);
-  const agentEnd = rest.indexOf("/");
-  if (agentEnd === -1) {
-    return undefined;
-  }
-  const afterAgent = rest.slice(agentEnd + 1);
-  const kindEnd = afterAgent.indexOf("/");
-  return kindEnd === -1 ? afterAgent : afterAgent.slice(0, kindEnd);
-}
-
-function isLogKey(key: string): boolean {
-  return frameworkFileKind(key) === "logs";
-}
-
-function encodeDocument(key: string, value: JsonValue): Uint8Array {
-  // start.log is raw UTF-8, not a JSON document. Stringify would quote
-  // every line and store a JSON string literal instead of the tee.
-  if (isLogKey(key)) {
-    return new TextEncoder().encode(typeof value === "string" ? value : JSON.stringify(value));
-  }
-  return new TextEncoder().encode(JSON.stringify(value));
-}
-
-function decodeDocument(key: string, bytes: Uint8Array): JsonValue {
-  const text = new TextDecoder().decode(bytes);
-  if (isLogKey(key)) {
-    return text;
-  }
-  try {
-    return JSON.parse(text) as JsonValue;
-  } catch (error) {
-    throw new Error(
-      `framework file storage: stored document at "${key}" is not JSON (${
-        error instanceof Error ? error.message : String(error)
-      })`,
-    );
-  }
-}
-
-/**
- * Split one storage core by key kind: framework session state to `files`,
- * everything else to `kv`. Spread over the KV backend when building the
- * full definition so its `evals` group (and the cursor-hosted marker)
- * rides along untouched; wrap the KV `cas` group with
- * {@link frameworkGuardedCas} rather than spreading it as-is.
- */
-export function composeFrameworkStorage(input: {
-  kv: FileSinkStorageCore;
-  files: FileSinkStorageCore;
-}): FileSinkStorageCore & Pick<StorageConfig, "listNewest"> {
-  const route = (key: string): FileSinkStorageCore =>
-    isFrameworkFileKey(key) ? input.files : input.kv;
-  return {
-    put: (key, value, ctx) => route(key).put(key, value, ctx),
-    async putMany(entries, ctx) {
-      // Partition by destination store, batch each side, and reassemble
-      // per-entry outcomes in input order.
-      const indexed = entries.map((entry, index) => ({ entry, index }));
-      const results: Array<{ key: string; error?: unknown }> = entries.map(entry => ({
-        key: entry.key,
-      }));
-      for (const core of [input.files, input.kv]) {
-        const side = indexed.filter(({ entry }) => route(entry.key) === core);
-        if (side.length === 0) {
-          continue;
-        }
-        if (core.putMany === undefined) {
-          // No batch write on this side (the KV proxy): sequential puts,
-          // preserving the strict one-at-a-time ordering it promises.
-          for (const { entry, index } of side) {
-            try {
-              await core.put(entry.key, entry.value, ctx);
-            } catch (error) {
-              results[index] = { key: entry.key, error };
-            }
-          }
-          continue;
-        }
-        const settled = await core.putMany(
-          side.map(({ entry }) => entry),
-          ctx,
-        );
-        for (let i = 0; i < side.length; i += 1) {
-          const target = side[i];
-          const outcome = settled[i];
-          if (target !== undefined && outcome !== undefined) {
-            results[target.index] = outcome;
-          }
-        }
-      }
-      return results;
-    },
-    get: (key, ctx) => route(key).get(key, ctx),
-    delete: (key, ctx) => route(key).delete(key, ctx),
-    list: (prefix, ctx) => route(prefix).list(prefix, ctx),
-    // Session records — the only `listNewest` consumer — are framework file
-    // keys, and the file store has no write-time ordering. Spreading the KV
-    // backend's `listNewest` through would query rows that live elsewhere
-    // (stale KV leftovers, or nothing), so the composed core explicitly has
-    // none and the engine falls back to the routed `list`.
-    listNewest: undefined,
-  };
-}
-
-/**
- * The KV backend's conditional writes, refusing framework-file keys.
- *
- * CAS runs on the KV proxy (a database row version); the plain core routes
- * framework session state to the file store. A future coordination path
- * that CASes a `session/` or `continuation/` key would otherwise read and
- * write a different store than the plain path — silent split-brain. Fail
- * loudly instead; nothing in the package CASes those kinds today.
- */
-export function frameworkGuardedCas(
-  cas: NonNullable<StorageConfig["cas"]>,
-): NonNullable<StorageConfig["cas"]> {
-  const refuse = (key: string): void => {
-    if (isFrameworkFileKey(key)) {
-      throw new Error(
-        `framework file storage: conditional writes are KV-only, but "${key}" routes to the framework file store`,
-      );
-    }
-  };
-  return {
-    getWithVersion: (key, ctx) => {
-      refuse(key);
-      return cas.getWithVersion(key, ctx);
-    },
-    putIfAbsent: (key, value, ctx) => {
-      refuse(key);
-      return cas.putIfAbsent(key, value, ctx);
-    },
-    putIfVersion: (key, value, expectedVersion, ctx) => {
-      refuse(key);
-      return cas.putIfVersion(key, value, expectedVersion, ctx);
-    },
-    listKeys: (prefix, ctx) => {
-      refuse(prefix);
-      return cas.listKeys(prefix, ctx);
-    },
-  };
-}

package/src/internal/framework-storage-selection.ts

@@ -1,156 +0,0 @@
-/**
- * Which backend framework session state is mirrored to.
- *
- * Framework state — session records, event chunks, the continuation index —
- * is how a session outlives the process that served it. On architecture v1
- * that mirror exists only when the agent author wrote `agent/storage.ts`,
- * which makes platform durability an agent-level decision: of the
- * first-party agents, some choose `cursorHostedStorage()` and some choose
- * `fileKv()` (pod-local disk, lost on pod replacement), and one selects
- * between them at runtime by reading the deployment-id environment variable
- * itself.
- *
- * That selection is a hosting-mode question, not an authoring question.
- * Architecture v2 moves it here: `agent/storage.ts` is rejected at
- * discovery (error diagnostic, so serve and deploy fail early), and the
- * platform picks the default. Architecture v1 with no authored file now
- * uses the same hosted-vs-self-hosted split, so deleting `agent/storage.ts`
- * (required to deploy the same tree onto v2) does not drop the Cursor-hosted
- * session mirror on a still-v1 pod.
- *
- * - **Cursor-managed hosting** (the deployment-generation environment
- *   variable is set, same signal that registers `GET /v1/manifest`):
- *   the deployment's **framework-level file store**
- *   (`AGENT_SERVE_FRAMEWORK_STORE_SOURCE_ID`, bound at task time) holds
- *   session records, event transcripts, and the continuation index —
- *   file-shaped state on file storage, apart from the author-facing user
- *   store. Author `host.kv`, eval runs, and conditional writes ride the
- *   AgentSDK v2 KV proxy (cursor-hosted-v2.ts), which resolves the
- *   pod service account to the factorydb deployment row (the v1 Bugbot
- *   proxy cannot resolve v2 pods at all). Framework session state never
- *   routes to the KV proxy — the composite splits by key kind — so
- *   transcripts stay off the author-reachable KV namespace. The API key
- *   resolves through the full credential chain on every call because hosted
- *   freeze snapshots listen unsigned and the binder drops the key file
- *   after restore.
- * - **Self-hosted**: no mirror. `--state-root` is the durable copy, which
- *   is correct when the operator owns the disk.
- *
- * v1 still honors an authored `agent/storage.ts` when present. Hosted v1
- * pods with no authored file get the Cursor-hosted lazy mirror (gated on
- * `AGENT_SERVE_DEPLOYMENT_ID`, the same signal the previous authored sinks
- * used). Self-hosted v1 with no authored file stays disk-only.
- *
- * Local disk is not part of this decision. `<stateRoot>/sessions/<id>/`
- * already holds `session.json` and `events.ndjson` unconditionally, through
- * the session store; what this selects is the durable mirror *beyond* the
- * pod's filesystem.
- */
-
-import { cursorHostedFiles } from "../files-backends/cursor-hosted.js";
-import { defineStorage, type StorageDefinition } from "../storage.js";
-import {
-  AGENT_SERVE_DEPLOYMENT_ID_ENV_VAR,
-  cursorHostedStorage,
-} from "../storage-backends/cursor-hosted.js";
-import { cursorHostedStorageV2 } from "../storage-backends/cursor-hosted-v2.js";
-import type { AgentArchitecture } from "../types.js";
-import { resolveApiKeySync } from "./cursor/credentials.js";
-import {
-  composeFrameworkStorage,
-  fileSinkStorageCore,
-  frameworkGuardedCas,
-} from "./framework-file-storage.js";
-import { resolveAgentV2Hosting } from "./v2-hosting.js";
-
-export interface FrameworkStorageSelectionInput {
-  /** `agent/storage.ts`, when the author wrote one (v1 only: discovery rejects it on v2). */
-  readonly authored: StorageDefinition | undefined;
-  /** {@link AgentConfig.architecture}; discovery fills `"v2"` when omitted. */
-  readonly architecture?: AgentArchitecture | undefined;
-  /** Environment override for tests; defaults to `process.env`. */
-  readonly env?: Record<string, string | undefined>;
-}
-
-/**
- * Pick the backend for framework session state.
- *
- * Returns `undefined` when there is no mirror, in which case the pod's local
- * disk is the only copy.
- */
-export function selectFrameworkStorageDefinition(
-  input: FrameworkStorageSelectionInput,
-): StorageDefinition | undefined {
-  if (input.architecture !== "v2") {
-    if (input.authored !== undefined) {
-      return input.authored;
-    }
-    const env = input.env ?? process.env;
-    if ((env[AGENT_SERVE_DEPLOYMENT_ID_ENV_VAR] ?? "").trim() !== "") {
-      // Hosted v1 pod with no authored sink: keep the Cursor-hosted
-      // mirror (lazy restore) so agents can delete `agent/storage.ts`
-      // without losing durability while they still run architecture v1.
-      return defineStorage({
-        name: "cursor-hosted (lazy restore)",
-        policy: { restore: "off" },
-        ...cursorHostedStorage(),
-      });
-    }
-    return undefined;
-  }
-  if (input.authored !== undefined) {
-    // Discovery rejects agent/storage.ts on v2 before an engine is built;
-    // an authored definition reaching this point is a wiring bug. Raise
-    // rather than silently discard what the author believes is configured.
-    throw new Error(
-      'defineStorage (agent/storage.ts) is not supported on architecture "v2": storage is platform-selected. Delete the file.',
-    );
-  }
-  const hosting = resolveAgentV2Hosting({
-    architecture: input.architecture,
-    env: input.env as NodeJS.ProcessEnv | undefined,
-  });
-  if (hosting.kind !== "cursor-managed") {
-    // Self-hosted v2: the state root is the durable copy.
-    return undefined;
-  }
-  // Hosted v2 pods wake per delivery: bulk-restoring up to the default
-  // 1000 sessions on every boot is waste (and against the file-store
-  // backend it is per-key HTTP round trips before the listener even
-  // comes up). Follow-ups restore lazily by continuation or session id;
-  // GET /v1/sessions lists from the sink either way.
-  //
-  // Events flush at turn end. drainSessionDurability still forces the
-  // record onto the sink before the execution reply.
-  const policy = {
-    restore: "off",
-  } as const;
-  // Full chain (env → bind file → stored login): frozen engines listen
-  // unsigned and bind store ids + CURSOR_API_KEY at task time, after this
-  // definition is constructed.
-  const resolveApiKey = (): string | undefined => resolveApiKeySync()?.apiKey;
-  // v2 pods carry a factorydb-bound service account, which the v1 Bugbot
-  // storage proxy cannot resolve; author KV, CAS coordination, and the
-  // eval/A-B tables speak the AgentSDK v2 KV proxy instead. It also carries
-  // the cursor-hosted marker, so GET /v1/sessions prefers the durable list
-  // (session records are on the framework store, which the composed core
-  // lists).
-  const kv = cursorHostedStorageV2({ resolveApiKey });
-  return defineStorage({
-    name: "cursor-hosted (framework files)",
-    policy,
-    ...kv,
-    ...composeFrameworkStorage({
-      kv,
-      files: fileSinkStorageCore(
-        cursorHostedFiles({
-          resolveStoreSourceId: () => hosting.resolveStoreIds().frameworkStoreSourceId,
-          resolveApiKey,
-        }),
-      ),
-    }),
-    // CAS stays on the KV proxy but must refuse framework-file keys, or a
-    // future coordination path would split-brain against the plain core.
-    cas: frameworkGuardedCas(kv.cas),
-  });
-}

package/src/internal/frontmatter.ts

@@ -1,108 +0,0 @@
-/**
- * Frontmatter parsers. Authored markdown (skill descriptions, schedule cron
- * expressions) uses the flat `key: value` scalar subset; Cursor plugin
- * markdown is full YAML (folded descriptions, lists).
- */
-
-import { JSON_SCHEMA, load as parseYaml } from "js-yaml";
-
-export interface ParsedFrontmatter {
-  data: Record<string, string>;
-  body: string;
-}
-
-export interface ParsedYamlFrontmatter {
-  data: Record<string, unknown>;
-  body: string;
-  /** Why the block did not parse as a YAML mapping; `data` is then empty. */
-  error?: string;
-}
-
-const FRONTMATTER_OPEN = /^---\s*$/;
-const YAML_FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)([\s\S]*)$/;
-
-/** YAML frontmatter with the JSON schema (no custom tags). */
-export function parseYamlFrontmatter(source: string): ParsedYamlFrontmatter {
-  const match = YAML_FRONTMATTER.exec(source);
-  if (match === null) {
-    return { data: {}, body: source };
-  }
-  const body = match[2] ?? "";
-  let data: unknown;
-  try {
-    data = parseYaml(match[1] ?? "", { schema: JSON_SCHEMA });
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    return { data: {}, body, error: message };
-  }
-  if (data === undefined || data === null) {
-    return { data: {}, body };
-  }
-  if (typeof data !== "object" || Array.isArray(data)) {
-    return { data: {}, body, error: "frontmatter is not a mapping" };
-  }
-  return { data: data as Record<string, unknown>, body };
-}
-
-export function parseFrontmatter(source: string): ParsedFrontmatter {
-  const lines = source.split(/\r?\n/);
-  if (lines.length === 0 || !FRONTMATTER_OPEN.test(lines[0] ?? "")) {
-    return { data: {}, body: source };
-  }
-
-  let closeIndex = -1;
-  for (let i = 1; i < lines.length; i++) {
-    if (FRONTMATTER_OPEN.test(lines[i] ?? "")) {
-      closeIndex = i;
-      break;
-    }
-  }
-  if (closeIndex === -1) {
-    return { data: {}, body: source };
-  }
-
-  const data: Record<string, string> = {};
-  for (const line of lines.slice(1, closeIndex)) {
-    if (line.trim() === "" || line.trim().startsWith("#")) {
-      continue;
-    }
-    const separator = line.indexOf(":");
-    if (separator === -1) {
-      continue;
-    }
-    const key = line.slice(0, separator).trim();
-    if (key === "") {
-      continue;
-    }
-    data[key] = unquote(line.slice(separator + 1).trim());
-  }
-
-  const body = lines
-    .slice(closeIndex + 1)
-    .join("\n")
-    .replace(/^\n+/, "");
-  return { data, body };
-}
-
-export function serializeFrontmatter(data: Record<string, string>): string {
-  const lines = Object.entries(data).map(([key, value]) => `${key}: ${quoteIfNeeded(value)}`);
-  return `---\n${lines.join("\n")}\n---\n`;
-}
-
-function unquote(value: string): string {
-  if (
-    value.length >= 2 &&
-    ((value.startsWith('"') && value.endsWith('"')) ||
-      (value.startsWith("'") && value.endsWith("'")))
-  ) {
-    return value.slice(1, -1);
-  }
-  return value;
-}
-
-function quoteIfNeeded(value: string): string {
-  if (/[:#'"\n]/.test(value)) {
-    return JSON.stringify(value);
-  }
-  return value;
-}