@cursor/bdk 0.2.3 → 0.2.4

package/src/internal/conversation-mirror.ts

@@ -1,423 +0,0 @@
-/**
- * Durable mirror for the SDK runner's conversation store.
- *
- * The Cursor SDK keeps each local conversation in SQLite under the engine's
- * state root (`runner/index.db` + `runner/agents/agent-<hash>/store.db`).
- * That disk dies with the pod: on architecture v2, session **records** and
- * event chunks survive replacement through the control-plane storage mirror
- * (framework-storage-selection.ts), but the conversation itself was never
- * hydrated anywhere — a replacement pod resumed every thread as a fresh
- * conversation.
- *
- * This module mirrors the conversation through the SDK's own store APIs —
- * the agent document (which carries `sdkMetadata.blobEncryptionKey`, without
- * which the checkpoint blobs cannot be decrypted) plus its content-addressed
- * checkpoint blobs — into the deployment's **framework-level** file store
- * (`AGENT_SERVE_FRAMEWORK_STORE_SOURCE_ID`), alongside session records and
- * transcripts and apart from the author-facing user store. The store is an
- * Agent Store reached over `/v0/agent-serve-files` presigned URLs — **not
- * mounted** as a filesystem in the engine VM (the FUSE mount at
- * {@link DEPLOYMENT_STORE_MOUNT_PATH} exists only on cloud-runtime VMs) —
- * so the mirror moves bytes through the {@link FileSink} contract instead.
- *
- * Going through the store APIs rather than copying `store.db` files sidesteps
- * WAL consistency and the shared `index.db` (per-session raw copies would
- * clobber other sessions' rows); checkpoint blobs are content-addressed, so
- * repeat persists upload only what is new.
- *
- * Timing: the runner hydrates before `Agent.resume` (so a follow-up landing
- * on a fresh pod — including a v2 hosted-execution delivery — finds the
- * conversation before the turn runs) and persists after each local turn
- * settles, **awaited**, because a hosted pod can be parked immediately after
- * the execution reply.
- *
- * Run rows and run events are deliberately not mirrored: they are per-pod
- * bookkeeping (turn numbers, stream offsets), and the durable session event
- * stream already lives in the control-plane storage mirror.
- */
-
-import type { LocalAgentDocument, LocalAgentStore } from "@cursor/sdk";
-import { agentSdkAgentStoreKeys, type FileSink } from "../files.js";
-import { cursorHostedFiles } from "../files-backends/cursor-hosted.js";
-import type { AgentProject } from "../types.js";
-import { mapBounded } from "./bounded.js";
-import { resolveApiKeySync } from "./cursor/credentials.js";
-import { describeError } from "./describe-error.js";
-import { resolveAgentV2Hosting } from "./v2-hosting.js";
-
-/**
- * Persist/restore one SDK conversation between a {@link LocalAgentStore} and
- * durable file storage. Implemented by {@link createConversationMirror};
- * consumed by the SDK runner.
- */
-export interface ConversationMirror {
-  /**
-   * Restore `sdkAgentId`'s conversation into `store` when the store does not
-   * already hold it. Resolves `true` when a conversation was restored,
-   * `false` on a definitive miss (never persisted, or already local — the
-   * caller falls through to its fresh-conversation path). A sink **failure**
-   * propagates: an outage must fail the turn (retryable) rather than
-   * silently fork the thread onto a fresh conversation.
-   */
-  hydrate(store: LocalAgentStore, sdkAgentId: string): Promise<boolean>;
-  /**
-   * Mirror `sdkAgentId`'s conversation from `store` to the sink
-   * (last write wins). No-op until the conversation has a checkpoint.
-   */
-  persist(store: LocalAgentStore, sdkAgentId: string): Promise<void>;
-}
-
-/** Wire shape at {@link agentSdkAgentStoreKeys.conversationManifest}. */
-interface ConversationManifestV1 {
-  v: 1;
-  /** The SDK agent document, verbatim apart from `activeRunId` (nulled). */
-  agent: LocalAgentDocument;
-  /** Checkpoint blob ids present under the conversation's blob prefix. */
-  blobIds: string[];
-  persistedAtMs: number;
-}
-
-export interface CreateConversationMirrorOptions {
-  sink: FileSink;
-  /** Agent name baked into every minted key. */
-  agentName: string;
-  logger?: (line: string) => void;
-}
-
-/** Build a {@link ConversationMirror} over a {@link FileSink}. */
-export function createConversationMirror(
-  options: CreateConversationMirrorOptions,
-): ConversationMirror {
-  const { sink, agentName } = options;
-  const logger = options.logger ?? (() => {});
-  /**
-   * Blob ids known to be in the sink, per SDK agent id (upload dedupe).
-   * Bounded oldest-out like the files backend's etag cache: a resident
-   * engine touches an unbounded number of conversations over its lifetime,
-   * and a miss costs one manifest read, never correctness.
-   */
-  const mirrored = new Map<string, Set<string>>();
-  const rememberMirrored = (sdkAgentId: string, blobIds: Set<string>): void => {
-    if (!mirrored.has(sdkAgentId) && mirrored.size >= MAX_TRACKED_CONVERSATIONS) {
-      const oldest = mirrored.keys().next();
-      if (!oldest.done) {
-        mirrored.delete(oldest.value);
-      }
-    }
-    mirrored.set(sdkAgentId, blobIds);
-  };
-  /**
-   * Content of the last manifest each conversation **successfully** wrote
-   * (minus `persistedAtMs`, which changes on every call by construction).
-   * A persist whose agent document and blob list are unchanged skips the
-   * manifest rewrite — `persist` runs on every turn boundary, but most
-   * boundaries between checkpoints change nothing durable. Same bound and
-   * eviction as `mirrored`; a miss only costs a redundant rewrite.
-   */
-  const lastManifestContent = new Map<string, string>();
-  const rememberManifest = (sdkAgentId: string, content: string): void => {
-    if (
-      !lastManifestContent.has(sdkAgentId) &&
-      lastManifestContent.size >= MAX_TRACKED_CONVERSATIONS
-    ) {
-      const oldest = lastManifestContent.keys().next();
-      if (!oldest.done) {
-        lastManifestContent.delete(oldest.value);
-      }
-    }
-    lastManifestContent.set(sdkAgentId, content);
-  };
-  /**
-   * Per-conversation serialization so a persist cannot interleave with a
-   * hydrate (or another persist) for the same conversation. Entries are
-   * removed once their chain settles as the tail, so the map tracks only
-   * conversations with work in flight.
-   */
-  const chains = new Map<string, Promise<unknown>>();
-
-  function serialize<T>(sdkAgentId: string, run: () => Promise<T>): Promise<T> {
-    const previous = chains.get(sdkAgentId) ?? Promise.resolve();
-    const next = previous.then(run, run);
-    const stored = next
-      .catch(() => {})
-      .then(() => {
-        if (chains.get(sdkAgentId) === stored) {
-          chains.delete(sdkAgentId);
-        }
-      });
-    chains.set(sdkAgentId, stored);
-    return next;
-  }
-
-  async function mirroredBlobIds(sdkAgentId: string): Promise<Set<string>> {
-    const cached = mirrored.get(sdkAgentId);
-    if (cached !== undefined) {
-      return cached;
-    }
-    // Seed from the previous manifest so a fresh pod does not re-upload the
-    // whole history on its first persist. A miss, an unusable manifest, or
-    // a failed read seeds empty — re-uploading is wasteful, never wrong.
-    const seeded = new Set<string>();
-    try {
-      const read = await readManifest(sink, agentName, sdkAgentId);
-      if (read.outcome === "found") {
-        for (const blobId of read.manifest.blobIds) {
-          seeded.add(blobId);
-        }
-      }
-    } catch (error) {
-      logger(
-        `[agent-sdk] conversation mirror: could not read the prior manifest for ${sdkAgentId} (${describeError(error)}); re-uploading blobs`,
-      );
-    }
-    rememberMirrored(sdkAgentId, seeded);
-    return seeded;
-  }
-
-  return {
-    persist(store, sdkAgentId): Promise<void> {
-      return serialize(sdkAgentId, async () => {
-        const document = await store.agents.get({ agentId: sdkAgentId });
-        if (document === null || document.latestCheckpoint == null) {
-          // Nothing restorable yet (no conversation, or no checkpoint).
-          return;
-        }
-        const uploaded = await mirroredBlobIds(sdkAgentId);
-        const blobIds = await listCheckpointBlobIds(store, sdkAgentId);
-        for (const blobId of blobIds) {
-          if (uploaded.has(blobId)) {
-            continue;
-          }
-          const bytes = await store.checkpoints.get({
-            agentId: sdkAgentId,
-            blobId,
-          });
-          if (bytes === null) {
-            continue;
-          }
-          await sink.put(
-            agentSdkAgentStoreKeys.conversationBlob(agentName, sdkAgentId, blobId),
-            bytes,
-          );
-          // Content-addressed: once in the sink, never re-uploaded.
-          uploaded.add(blobId);
-        }
-        const manifest: ConversationManifestV1 = {
-          v: 1,
-          // The referenced run is pod-local bookkeeping and is not mirrored;
-          // a hydrated store must not point at a run row it does not hold.
-          agent: { ...document, activeRunId: null },
-          blobIds: blobIds.filter(blobId => uploaded.has(blobId)),
-          persistedAtMs: Date.now(),
-        };
-        // Skip the rewrite when nothing durable changed. `persistedAtMs`
-        // is excluded from the comparison — it differs on every call by
-        // construction and carries no restore semantics.
-        const content = JSON.stringify({
-          agent: manifest.agent,
-          blobIds: manifest.blobIds,
-        });
-        if (lastManifestContent.get(sdkAgentId) === content) {
-          return;
-        }
-        lastManifestContent.delete(sdkAgentId);
-        // Manifest last: it only ever references blobs already uploaded.
-        await sink.put(
-          agentSdkAgentStoreKeys.conversationManifest(agentName, sdkAgentId),
-          new TextEncoder().encode(JSON.stringify(manifest)),
-        );
-        rememberManifest(sdkAgentId, content);
-      });
-    },
-
-    hydrate(store, sdkAgentId): Promise<boolean> {
-      return serialize(sdkAgentId, async () => {
-        const existing = await store.agents.get({ agentId: sdkAgentId });
-        if (existing !== null) {
-          return false;
-        }
-        const read = await readManifest(sink, agentName, sdkAgentId);
-        if (read.outcome === "miss") {
-          return false;
-        }
-        if (read.outcome === "unusable") {
-          // Definitive, non-transient state (a future manifest version
-          // during a rolling redeploy, or corruption): retrying would fail
-          // identically forever, so fall through to the caller's
-          // fresh-conversation path instead of wedging the session.
-          logger(
-            `[agent-sdk] conversation mirror: the manifest for ${sdkAgentId} is unusable (${read.reason}); treating the conversation as unrestorable`,
-          );
-          return false;
-        }
-        const manifest = read.manifest;
-        const rootBlobId = manifest.agent.latestCheckpoint?.rootBlobId;
-        if (rootBlobId === undefined || !manifest.blobIds.includes(rootBlobId)) {
-          logger(
-            `[agent-sdk] conversation mirror: the manifest for ${sdkAgentId} does not list its root checkpoint blob; treating the conversation as unrestorable`,
-          );
-          return false;
-        }
-        // This sits on the resume critical path. Prefer the sink's batched
-        // read — on the hosted sink that is one presign call per 100 blobs
-        // instead of one per blob, keeping a checkpoint-heavy restore under
-        // the store's per-deployment rate budget — and fall back to
-        // bounded-parallel per-blob gets elsewhere.
-        const blobKeys = manifest.blobIds.map(blobId =>
-          agentSdkAgentStoreKeys.conversationBlob(agentName, sdkAgentId, blobId),
-        );
-        const blobBodies =
-          sink.getMany !== undefined
-            ? await sink.getMany(blobKeys)
-            : await mapBounded(blobKeys, HYDRATE_DOWNLOAD_CONCURRENCY, key => sink.get(key));
-        const bodies = manifest.blobIds.map((blobId, index) => ({
-          blobId,
-          body: blobBodies[index],
-        }));
-        const missing = bodies.filter(entry => entry.body === undefined);
-        if (missing.length > 0) {
-          // The manifest lists exactly what a previous persist uploaded, so
-          // any definitive absence is store loss — and the checkpoint graph
-          // may reach any listed blob, not just the root. Restoring a
-          // partial graph would create an agent row whose resume succeeds
-          // and whose checkpoint walk then fails unrecoverably.
-          logger(
-            `[agent-sdk] conversation mirror: ${missing.length} checkpoint blob(s) for ${sdkAgentId} are missing from the sink; treating the conversation as unrestorable`,
-          );
-          return false;
-        }
-        const restored = new Set<string>();
-        for (const entry of bodies) {
-          const body = entry.body as NonNullable<typeof entry.body>;
-          const bytes = body instanceof Uint8Array ? body : body.body;
-          if (
-            (await store.checkpoints.get({
-              agentId: sdkAgentId,
-              blobId: entry.blobId,
-            })) === null
-          ) {
-            await store.checkpoints.create({
-              agentId: sdkAgentId,
-              blobId: entry.blobId,
-              data: bytes,
-            });
-          }
-          restored.add(entry.blobId);
-        }
-        await store.agents.create({
-          agent: { ...manifest.agent, activeRunId: null },
-        });
-        rememberMirrored(sdkAgentId, restored);
-        logger(
-          `[agent-sdk] conversation mirror: restored the conversation for ${sdkAgentId} (${restored.size} checkpoint blob(s))`,
-        );
-        return true;
-      });
-    },
-  };
-}
-
-/** Oldest-out cap on the per-conversation upload-dedupe cache. */
-const MAX_TRACKED_CONVERSATIONS = 1_000;
-
-/** Parallel blob downloads during hydrate (resume critical path). */
-const HYDRATE_DOWNLOAD_CONCURRENCY = 8;
-
-type ManifestRead =
-  /** No manifest was ever persisted (definitive miss). */
-  | { outcome: "miss" }
-  /**
-   * A manifest exists but cannot be used (future version, corruption,
-   * wrong agent). Definitive and non-transient — callers must not retry,
-   * and must not treat it as a sink outage.
-   */
-  | { outcome: "unusable"; reason: string }
-  | { outcome: "found"; manifest: ConversationManifestV1 };
-
-/**
- * Read the persisted manifest. Sink transport failures propagate (an
- * outage must fail the follow-up, not fork the thread); everything the
- * bytes themselves can be wrong about is reported as `unusable`.
- */
-async function readManifest(
-  sink: FileSink,
-  agentName: string,
-  sdkAgentId: string,
-): Promise<ManifestRead> {
-  const body = await sink.get(agentSdkAgentStoreKeys.conversationManifest(agentName, sdkAgentId));
-  if (body === undefined) {
-    return { outcome: "miss" };
-  }
-  const bytes = body instanceof Uint8Array ? body : body.body;
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(new TextDecoder().decode(bytes));
-  } catch {
-    return { outcome: "unusable", reason: "not JSON" };
-  }
-  if (parsed === null || typeof parsed !== "object" || (parsed as { v?: unknown }).v !== 1) {
-    return { outcome: "unusable", reason: "unsupported manifest version" };
-  }
-  const manifest = parsed as ConversationManifestV1;
-  if (
-    manifest.agent === null ||
-    typeof manifest.agent !== "object" ||
-    manifest.agent.agentId !== sdkAgentId ||
-    !Array.isArray(manifest.blobIds)
-  ) {
-    return { outcome: "unusable", reason: "malformed manifest" };
-  }
-  return { outcome: "found", manifest };
-}
-
-async function listCheckpointBlobIds(
-  store: LocalAgentStore,
-  sdkAgentId: string,
-): Promise<string[]> {
-  const blobIds: string[] = [];
-  let cursor: string | undefined;
-  do {
-    const page = await store.checkpoints.list({
-      filter: { agentIds: [sdkAgentId], cursor },
-    });
-    blobIds.push(...page.items);
-    cursor = page.nextCursor;
-  } while (cursor !== undefined);
-  return blobIds;
-}
-
-/**
- * Whether (and over which sink) this serve process mirrors conversations.
- *
- * Selected for architecture-v2 agents on Cursor-managed hosting — the same
- * generation signal as framework-storage-selection.ts, plus a provisioned
- * **framework-level** file store: conversation state is engine-owned, so it
- * lives with session records and transcripts, never on the author-facing
- * user store. Self-hosted v2 keeps everything on the state root (the
- * operator owns the disk), and v1 keeps today's behavior while it runs.
- */
-export function selectConversationMirror(input: {
-  project: AgentProject;
-  logger?: (line: string) => void;
-  env?: Record<string, string | undefined>;
-}): ConversationMirror | undefined {
-  const hosting = resolveAgentV2Hosting({
-    architecture: input.project.agent.architecture,
-    env: input.env as NodeJS.ProcessEnv | undefined,
-  });
-  if (hosting.kind !== "cursor-managed") {
-    return undefined;
-  }
-  return createConversationMirror({
-    sink: cursorHostedFiles({
-      resolveStoreSourceId: () => hosting.resolveStoreIds().frameworkStoreSourceId,
-      // Full chain (env → key file → stored login), resolved lazily: frozen
-      // engines listen unsigned and only gain a credential at task time,
-      // after this sink is constructed. Hosted deliveries have consumed the
-      // bind file into CURSOR_API_KEY by then, so this resolves from env.
-      resolveApiKey: () => resolveApiKeySync()?.apiKey,
-    }),
-    agentName: input.project.name,
-    logger: input.logger,
-  });
-}