trajectories 0.0.0 → 0.1.1

package/legacy/src/native/cursor.ts

@@ -0,0 +1,647 @@
+import type { Database } from "bun:sqlite";
+import { closeSync, fstatSync, lstatSync, openSync, readdirSync, readSync } from "node:fs";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { basename, dirname, extname, join, resolve } from "node:path";
+import type { Diagnostic } from "@letta-ai/trajectory";
+import type { DiscoveredSession } from "../types.js";
+import {
+  MAX_NATIVE_BYTES, MAX_NATIVE_RECORDS, NativeInputError, nativeByteLimit, object, readBoundedText, reportNativeError,
+  safeNativeId, type NativeDiscoveryOptions, type NativeReadOptions, type NativeTranscript,
+} from "./common.js";
+import { withReadOnlyDb } from "./sqlite-ro.js";
+
+const CAPTURE_READ_BYTES = 64 * 1024;
+const CAPTURE_PREFIX_ROWS = 256;
+const MAX_DEPTH = 12;
+// Format facts: docs/research/ledger/docs/research/2026-09-09-agentsview-native-discovery.md.
+const COMPOSER_PREFIX = "composerData:";
+// Legacy tabs/bubbles: https://forum.cursor.com/t/how-do-i-export-chat-with-ai/144/34
+const LEGACY_CHAT_KEY = "workbench.panel.aichat.view.aichat.chatdata";
+const EXCLUDED_DIRECTORIES = new Set([
+  "node_modules", "plugins", "extensions", ".git", ".hg", ".svn", ".cache",
+  "cache", "cacheddata", "cachedextensions", "cachedprofilesdata", "logs", "telemetry",
+]);
+
+export function cursorRoots(): string[] {
+  const home = homedir();
+  const user = process.platform === "darwin" ? join(home, "Library/Application Support/Cursor/User")
+    : process.platform === "win32" ? join(process.env.APPDATA || join(home, "AppData/Roaming"), "Cursor/User")
+    : join(process.env.XDG_CONFIG_HOME || join(home, ".config"), "Cursor/User");
+  return [join(home, ".cursor"), join(user, "globalStorage"), join(user, "workspaceStorage")];
+}
+
+function supportedBlock(value: unknown): boolean {
+  if (!object(value)) return false;
+  switch (value.type) {
+    case "text": return typeof value.text === "string" && value.text.trim().length > 0;
+    case "thinking": return typeof value.thinking === "string" && value.thinking.trim().length > 0;
+    case "tool_use": return typeof value.name === "string" && value.name.length > 0 && "input" in value;
+    case "tool_result": return "content" in value && (typeof value.content === "string" || Array.isArray(value.content) || object(value.content));
+    default: return false;
+  }
+}
+
+function captureRow(value: unknown): boolean {
+  if (!object(value) || (value.role !== "user" && value.role !== "assistant") || !object(value.message)) return false;
+  const content = value.message.content;
+  return typeof content === "string" ? content.trim().length > 0 : Array.isArray(content) && content.some(supportedBlock);
+}
+
+function validCapture(path: string, options: NativeDiscoveryOptions): boolean {
+  const fd = openSync(path, "r");
+  try {
+    const size = fstatSync(fd).size;
+    let offset = 0;
+    let rows = 0;
+    let parts: Buffer[] = [];
+    const completeLine = (): boolean => {
+      const line = Buffer.concat(parts).toString("utf8").replace(/^\uFEFF/, "");
+      parts = [];
+      rows++;
+      try { return captureRow(JSON.parse(line)); } catch { return false; }
+    };
+    while (offset < size && offset < MAX_NATIVE_BYTES && rows < CAPTURE_PREFIX_ROWS) {
+      const chunk = Buffer.alloc(Math.min(CAPTURE_READ_BYTES, size - offset, MAX_NATIVE_BYTES - offset));
+      const count = readSync(fd, chunk, 0, chunk.length, offset);
+      if (!count) break;
+      offset += count;
+      let start = 0;
+      while (start < count && rows < CAPTURE_PREFIX_ROWS) {
+        const newline = chunk.indexOf(10, start);
+        const end = newline < 0 || newline >= count ? count : newline;
+        parts.push(chunk.subarray(start, end));
+        if (end < count && completeLine()) return true;
+        start = end + 1;
+      }
+    }
+    if (offset === size && parts.length && rows < CAPTURE_PREFIX_ROWS && completeLine()) return true;
+    const bounded = offset < size || rows >= CAPTURE_PREFIX_ROWS;
+    options.onDiagnostic?.({
+      code: bounded ? "incomplete_evidence" : "invalid_metadata", sourcePath: path,
+      message: bounded ? "Cursor capture could not be validated within the prefix limit." : "No supported Cursor capture messages found.",
+    });
+    return false;
+  } finally { closeSync(fd); }
+}
+
+export function discoverCursorSessions(roots: string[], options: NativeDiscoveryOptions): DiscoveredSession[] {
+  if (!Number.isSafeInteger(options.limit) || options.limit < 1) throw new RangeError("Cursor discovery limit must be positive.");
+  const seen = new Set<string>();
+  const items: DiscoveredSession[] = [];
+  function walk(path: string, depth: number): void {
+    if (seen.has(path)) return;
+    seen.add(path);
+    try {
+      const stat = lstatSync(path);
+      if (stat.isSymbolicLink()) return;
+      if (stat.isDirectory()) {
+        if (EXCLUDED_DIRECTORIES.has(basename(path).toLowerCase())) return;
+        if (depth > MAX_DEPTH) {
+          options.onDiagnostic?.({ code: "incomplete_evidence", sourcePath: path, message: "Cursor discovery reached its directory depth limit." });
+          return;
+        }
+        const entries = readdirSync(path, { withFileTypes: true });
+        const storage = basename(path);
+        if (storage === "globalStorage" || basename(dirname(path)) === "workspaceStorage") {
+          if (entries.some((entry) => entry.name === "state.vscdb" && entry.isFile())) walk(join(path, "state.vscdb"), depth + 1);
+          return;
+        }
+        for (const entry of entries) {
+          if (storage === "workspaceStorage" && !entry.isDirectory()) continue;
+          if (entry.isDirectory() || entry.isFile()) walk(join(path, entry.name), depth + 1);
+        }
+      } else if (stat.isFile() && extname(path).toLowerCase() === ".jsonl" && validCapture(path, options)) {
+        const id = basename(path, extname(path));
+        if (safeNativeId(id)) items.push({ id, source: "cursor", path, sizeBytes: stat.size, updatedAt: stat.mtime.toISOString() });
+      } else if (stat.isFile() && basename(path) === "state.vscdb") {
+        items.push(...discoverDatabase(path, options));
+      } else if (stat.isFile() && basename(path) === "store.db") {
+        items.push(...discoverBlobStore(path, options));
+      } else if (stat.isFile() && extname(path) === ".txt" && (depth === 0 || path.split(/[\\/]/).includes("agent-transcripts"))) {
+        options.onDiagnostic?.({ code: "incomplete_evidence", sourcePath: path, message: "Cursor text transcripts are unsupported; JSONL or supported SQLite history is required." });
+      }
+    } catch (error) {
+      if (object(error) && error.code === "ENOENT" && depth === 0) return;
+      reportNativeError(options, path);
+    }
+  }
+  for (const root of roots) walk(resolve(root), 0);
+  const ordered = items.sort((a, b) => (b.updatedAt ?? "").localeCompare(a.updatedAt ?? "") ||
+    Number(b.path.endsWith(join("globalStorage", "state.vscdb"))) - Number(a.path.endsWith(join("globalStorage", "state.vscdb"))) ||
+    a.path.localeCompare(b.path) || a.id.localeCompare(b.id));
+  const nativeIds = new Set<string>();
+  const deduplicated = ordered.filter((item) => {
+    if (!item.native) return true;
+    if (nativeIds.has(item.id)) return false;
+    nativeIds.add(item.id);
+    return true;
+  });
+  return options.select ? options.select(deduplicated) : deduplicated.slice(0, options.limit);
+}
+
+function hasTable(db: Database, table: "cursorDiskKV" | "ItemTable"): boolean {
+  if (!db.query("SELECT 1 FROM sqlite_schema WHERE type = 'table' AND name = ?").get(table)) return false;
+  // Validate before projection without relying on runtime-specific SQLite error codes.
+  const columns = new Set((db.query("SELECT lower(name) AS name FROM pragma_table_xinfo(?)").all(table) as { name: string }[])
+    .map((column) => column.name));
+  if (!columns.has("key") || !columns.has("value")) throw new NativeInputError("Unsupported Cursor SQLite schema: missing key or value column.");
+  return true;
+}
+
+function withCursorDb<T>(path: string, read: (db: Database) => T): T {
+  try { return withReadOnlyDb(path, read); }
+  catch (error) {
+    if (object(error) && ["SQLITE_ERROR", "SQLITE_CORRUPT", "SQLITE_NOTADB"].includes(String(error.code))) {
+      throw new NativeInputError("Unsupported or corrupt Cursor SQLite schema.");
+    }
+    throw error;
+  }
+}
+
+function nativeTime(value: unknown): string | undefined {
+  if ((typeof value !== "number" || !Number.isFinite(value) || value <= 0) && (typeof value !== "string" || !value.trim())) return;
+  const time = new Date(value as string | number);
+  return Number.isFinite(time.getTime()) ? time.toISOString() : undefined;
+}
+
+function discoverDatabase(path: string, options: NativeDiscoveryOptions): DiscoveredSession[] {
+  return withCursorDb(path, (db) => {
+    const hasComposers = hasTable(db, "cursorDiskKV");
+    const hasLegacy = hasTable(db, "ItemTable");
+    if (!hasComposers && !hasLegacy) {
+      options.onDiagnostic?.({ code: "invalid_metadata", sourcePath: path, message: "Unsupported Cursor database schema." });
+      return [];
+    }
+    // Project only keys and listing metadata; message bodies belong to the per-session reader.
+    const rows = hasComposers ? db.query(`SELECT key,
+      CASE WHEN json_valid(CAST(value AS TEXT)) THEN json_extract(CAST(value AS TEXT), '$.name') END AS title,
+      CASE WHEN json_valid(CAST(value AS TEXT)) THEN json_extract(CAST(value AS TEXT), '$.lastUpdatedAt') END AS updated,
+      CASE WHEN json_valid(CAST(value AS TEXT)) THEN json_type(CAST(value AS TEXT), '$.fullConversationHeadersOnly') END AS headerType,
+      CASE WHEN json_valid(CAST(value AS TEXT)) THEN json_array_length(CAST(value AS TEXT), '$.fullConversationHeadersOnly') END AS headerCount,
+      CASE WHEN json_valid(CAST(value AS TEXT)) THEN EXISTS(SELECT 1 FROM json_each(CAST(value AS TEXT), '$.conversationMap')) END AS hasInline
+      FROM cursorDiskKV WHERE key >= 'composerData:' AND key < 'composerData;'
+      ORDER BY updated DESC, key LIMIT ?`).all(MAX_NATIVE_RECORDS + 1) as { key: string; title: unknown; updated: unknown; headerType: unknown; headerCount: number | null; hasInline: number }[] : [];
+    if (rows.length > MAX_NATIVE_RECORDS) options.onDiagnostic?.({ code: "incomplete_evidence", sourcePath: path, message: "Cursor discovery reached its session record limit." });
+    const items: DiscoveredSession[] = [];
+    for (const row of rows.slice(0, MAX_NATIVE_RECORDS)) {
+      const id = row.key.slice(COMPOSER_PREFIX.length);
+      if (!safeNativeId(id)) {
+        options.onDiagnostic?.({ code: "invalid_metadata", sourcePath: path, message: "Cursor composer has an invalid native session ID." });
+        continue;
+      }
+      if (row.headerType === "array" && row.headerCount === 0 && !row.hasInline) {
+        options.onDiagnostic?.({ code: "incomplete_evidence", sourcePath: path, message: "Cursor session is an empty draft with zero conversation headers." });
+        continue;
+      }
+      if (row.headerType !== "array" || row.headerCount === 0) {
+        options.onDiagnostic?.({ code: "invalid_metadata", sourcePath: path, message: "Unsupported Cursor conversation layout; ordered headers are missing." });
+      }
+      items.push({ id, source: "cursor", path, native: { kind: "cursor-sqlite" },
+        updatedAt: nativeTime(row.updated),
+        ...(typeof row.title === "string" ? { title: row.title } : {}),
+      });
+    }
+    if (hasComposers && db.query("SELECT 1 FROM cursorDiskKV WHERE key >= 'agentKv:' AND key < 'agentKv;' LIMIT 1").get()) {
+      options.onDiagnostic?.({ code: "incomplete_evidence", sourcePath: path, message: "Cursor agentKv storage is opaque and was not decoded." });
+    }
+    if (hasLegacy) {
+      const shape = db.query(`SELECT CASE WHEN json_valid(CAST(value AS TEXT)) THEN json_type(CAST(value AS TEXT), '$.tabs') END AS type
+        FROM ItemTable WHERE key = ?`).get(LEGACY_CHAT_KEY) as { type: string | null } | null;
+      if (!shape) return items;
+      if (shape.type !== "array") {
+        options.onDiagnostic?.({ code: "invalid_metadata", sourcePath: path, message: "Unsupported or malformed Cursor legacy chatdata layout." });
+        return items;
+      }
+      const tabs = db.query(`SELECT json_extract(tab.value, '$.id') AS id,
+        COALESCE(json_extract(tab.value, '$.chatTitle'), json_extract(tab.value, '$.title')) AS title,
+        COALESCE(json_extract(tab.value, '$.lastSendTime'), json_extract(tab.value, '$.updatedAt'), json_extract(tab.value, '$.timestamp')) AS updated
+        FROM ItemTable AS store, json_each(CAST(store.value AS TEXT), '$.tabs') AS tab
+        WHERE store.key = ? AND tab.type = 'object' ORDER BY updated DESC, tab.key LIMIT ?`
+      ).all(LEGACY_CHAT_KEY, MAX_NATIVE_RECORDS + 1) as { id: unknown; title: unknown; updated: unknown }[];
+      if (tabs.length > MAX_NATIVE_RECORDS) options.onDiagnostic?.({ code: "incomplete_evidence", sourcePath: path, message: "Cursor legacy discovery reached its session record limit." });
+      for (const tab of tabs.slice(0, MAX_NATIVE_RECORDS)) {
+        if (!safeNativeId(tab.id)) {
+          options.onDiagnostic?.({ code: "invalid_metadata", sourcePath: path, message: "Cursor legacy chat has no valid native session ID." });
+          continue;
+        }
+        items.push({ id: tab.id, source: "cursor", path, native: { kind: "cursor-sqlite" },
+          updatedAt: nativeTime(tab.updated), ...(typeof tab.title === "string" ? { title: tab.title } : {}),
+        });
+      }
+    }
+    return items;
+  });
+}
+
+interface ReadBudget { bytes: number; rows: number; limit: number }
+type ContentBlock = Record<string, unknown>;
+interface CursorRow { id?: string; role: "user" | "assistant"; message: { content: ContentBlock[]; model?: string } }
+
+// Field allowlists keep cloud-sync keys, request contexts, and unrelated state out of the reader.
+const COMPOSER_FIELDS = ["composerId", "name", "fullConversationHeadersOnly", "conversationMap", "createdAt", "lastUpdatedAt"];
+const BUBBLE_FIELDS = ["bubbleId", "type", "text", "createdAt", "thinking", "isPlaceholder", "toolFormerData"];
+
+function readJsonRow(db: Database, key: string, budget: ReadBudget): Record<string, unknown> | undefined {
+  const meta = db.query("SELECT length(CAST(value AS BLOB)) AS bytes FROM cursorDiskKV WHERE key = ?").get(key) as { bytes: number | null } | null;
+  if (!meta) return;
+  if (meta.bytes === null) throw new NativeInputError("Incomplete Cursor row: missing JSON value.");
+  budget.bytes += meta.bytes;
+  budget.rows++;
+  if (budget.bytes > budget.limit) throw new NativeInputError("Cursor session exceeds the native byte limit.");
+  if (budget.rows > MAX_NATIVE_RECORDS) throw new NativeInputError("Cursor session exceeds the native record limit.");
+  const shape = db.query(`SELECT CASE WHEN json_valid(CAST(value AS TEXT)) THEN json_type(CAST(value AS TEXT)) END AS type
+    FROM cursorDiskKV WHERE key = ?`).get(key) as { type: string | null };
+  if (shape.type !== "object") throw new NativeInputError("Invalid Cursor JSON row: expected an object.");
+  const json = "CAST(value AS TEXT)";
+  const fields = key.startsWith(COMPOSER_PREFIX) ? COMPOSER_FIELDS : BUBBLE_FIELDS;
+  const projection = fields.map((field) => field === "name"
+    ? `'name', CASE WHEN json_type(${json}, '$.name') = 'text' THEN json_extract(${json}, '$.name') END`
+    : field === "thinking"
+    ? `'thinking', CASE WHEN json_type(${json}, '$.thinking') = 'object' THEN json_object('text', json_extract(${json}, '$.thinking.text')) END`
+    : field === "isPlaceholder"
+    ? `'isPlaceholder', CASE json_type(${json}, '$.isPlaceholder') WHEN 'true' THEN json('true') WHEN 'false' THEN json('false') END`
+    : `'${field}', json_extract(${json}, '$.${field}')`).join(", ");
+  const metadata = key.startsWith(COMPOSER_PREFIX)
+    ? `, 'cwd', json_extract(${json}, '$.workspaceIdentifier.uri.fsPath'),
+      'repoPath', json_extract(${json}, '$.trackedGitRepos[0].repoPath'),
+      'model', json_extract(${json}, '$.modelConfig.modelName')` : "";
+  let value: unknown;
+  const row = db.query(`SELECT json_object(${projection}${metadata}) AS value FROM cursorDiskKV WHERE key = ?`).get(key) as { value: string };
+  try { value = JSON.parse(row.value); }
+  catch { throw new NativeInputError("Invalid Cursor JSON row; transcript may be incomplete."); }
+  if (!object(value)) throw new NativeInputError("Unsupported Cursor JSON row: expected an object.");
+  return value;
+}
+
+function bubbleRow(bubble: Record<string, unknown>, id?: string, headerType?: unknown): CursorRow {
+  if (bubble.bubbleId != null && bubble.bubbleId !== id) throw new NativeInputError("Conflicting Cursor bubble IDs.");
+  const type = bubble.type == null || bubble.type === 0 ? headerType : bubble.type;
+  const role = type === 1 || type === "user" ? "user" : type === 2 || type === "ai" || type === "assistant" ? "assistant"
+    : type == null && (bubble.role === "user" || bubble.role === "assistant") ? bubble.role : undefined;
+  if (!role) throw new NativeInputError("Unsupported Cursor bubble type; transcript may be incomplete.");
+  const content: ContentBlock[] = [];
+  if (typeof bubble.text === "string" && bubble.text.length) content.push({ type: "text", text: bubble.text });
+  else if (typeof bubble.content === "string" && bubble.content.length) content.push({ type: "text", text: bubble.content });
+  if (bubble.thinking != null) {
+    if (!object(bubble.thinking) || typeof bubble.thinking.text !== "string") throw new NativeInputError("Unsupported Cursor thinking content.");
+    if (bubble.thinking.text.length) content.push({ type: "thinking", thinking: bubble.thinking.text });
+  }
+  if (bubble.toolFormerData !== undefined && bubble.toolFormerData !== null) {
+    if (!object(bubble.toolFormerData)) throw new NativeInputError("Unsupported Cursor toolFormerData.");
+    const tool = bubble.toolFormerData;
+    let input = tool.rawArgs;
+    if (typeof input === "string") { try { input = JSON.parse(input); } catch { /* Preserve unfinished/raw tool arguments as a string. */ } }
+    const callId = typeof tool.toolCallId === "string" && tool.toolCallId ? tool.toolCallId : undefined;
+    if (input !== undefined || typeof tool.name === "string") {
+      content.push({ type: "tool_use", ...(callId ? { id: callId } : {}),
+        ...(typeof tool.name === "string" ? { name: tool.name } : {}), ...(input !== undefined ? { input } : {}),
+      });
+    }
+    if (tool.result !== undefined) content.push({ type: "tool_result", ...(callId ? { tool_use_id: callId } : {}), content: tool.result });
+  }
+  // Retain the empty row so a completed placeholder cannot shift later source sequences.
+  if (!content.length && !(role === "assistant" && bubble.isPlaceholder === true)) {
+    throw new NativeInputError("Incomplete Cursor conversational bubble: missing message content.");
+  }
+  return { ...(id ? { id } : {}), role, message: { content } };
+}
+
+function readLegacySession(db: Database, id: string, budget: ReadBudget): NativeTranscript {
+  if (!hasTable(db, "ItemTable")) throw new NativeInputError("Missing Cursor composer session.");
+  const meta = db.query(`SELECT CASE WHEN json_valid(CAST(value AS TEXT)) THEN json_type(CAST(value AS TEXT), '$.tabs') END AS type
+    FROM ItemTable WHERE key = ?`).get(LEGACY_CHAT_KEY) as { type: string | null } | null;
+  if (!meta) throw new NativeInputError("Missing Cursor session.");
+  if (meta.type !== "array") throw new NativeInputError("Unsupported Cursor legacy chat JSON layout.");
+  const selection = `FROM ItemTable AS store, json_each(CAST(store.value AS TEXT), '$.tabs') AS tab
+    WHERE store.key = ? AND tab.type = 'object' AND json_extract(tab.value, '$.id') = ?`;
+  const matches = db.query(`SELECT length(CAST(tab.value AS BLOB)) AS bytes ${selection} LIMIT 2`).all(LEGACY_CHAT_KEY, id) as { bytes: number }[];
+  if (matches.length !== 1) throw new NativeInputError("Missing or conflicting Cursor legacy chat ID.");
+  budget.bytes += matches[0].bytes;
+  if (budget.bytes > budget.limit) throw new NativeInputError("Cursor session exceeds the native byte limit.");
+  const fields = ["chatTitle", "title", "bubbles", "messages", "createdAt", "updatedAt", "lastSendTime", "timestamp"];
+  const projection = fields.map((field) => field === "chatTitle" || field === "title"
+    ? `'${field}', CASE WHEN json_type(tab.value, '$.${field}') = 'text' THEN json_extract(tab.value, '$.${field}') END`
+    : `'${field}', json_extract(tab.value, '$.${field}')`).join(", ");
+  const selected = db.query(`SELECT json_object(${projection}) AS value ${selection}`).get(LEGACY_CHAT_KEY, id) as { value: string };
+  const tab = JSON.parse(selected.value) as Record<string, unknown>;
+  const bubbles = tab.bubbles ?? tab.messages;
+  if (!Array.isArray(bubbles)) throw new NativeInputError("Unsupported Cursor legacy message layout.");
+  if (bubbles.length >= MAX_NATIVE_RECORDS) throw new NativeInputError("Cursor session exceeds the native record limit.");
+  const lines: string[] = [];
+  const ids = new Set<string>();
+  let bytes = 0;
+  for (const bubble of bubbles) {
+    if (!object(bubble)) throw new NativeInputError("Invalid Cursor legacy bubble.");
+    const messageId = bubble.bubbleId ?? bubble.id;
+    if (messageId != null && !safeNativeId(messageId)) throw new NativeInputError("Invalid Cursor native message ID.");
+    if (typeof messageId === "string") {
+      if (ids.has(messageId)) throw new NativeInputError("Duplicate Cursor native message ID.");
+      ids.add(messageId);
+    }
+    const line = JSON.stringify(bubbleRow(bubble, messageId as string | undefined));
+    bytes += Buffer.byteLength(line) + 1;
+    if (bytes > budget.limit) throw new NativeInputError("Cursor transcript exceeds the native byte limit.");
+    lines.push(line);
+  }
+  const startedAt = nativeTime(tab.createdAt);
+  const endedAt = nativeTime(tab.lastSendTime ?? tab.updatedAt ?? tab.timestamp);
+  const title = typeof tab.chatTitle === "string" ? tab.chatTitle : typeof tab.title === "string" ? tab.title : undefined;
+  return { transcript: lines.length ? lines.join("\n") + "\n" : "",
+    ...(title !== undefined ? { title } : {}), ...(startedAt ? { startedAt } : {}), ...(endedAt ? { endedAt } : {}),
+  };
+}
+
+// Cursor agent chats live in ~/.cursor/chats/<workspace>/<agentId>/store.db as a
+// content-addressed blob store: one JSON `meta` row names the agent and its root
+// blob, the root is protobuf whose repeated field 1 lists the ordered message
+// blob IDs and whose field 9 is the workspace URI, and each message blob is JSON.
+// Block names differ from the capture format the trajectory adapter decodes
+// (tool-call/tool-result/reasoning here, tool_use/tool_result/thinking there), so
+// this reader translates them. Format facts: docs/research/2026-09-17-cursor-blobstore.md.
+const BLOB_MESSAGE_FIELD = 1;
+const BLOB_WORKSPACE_FIELD = 9;
+const BLOB_ID_BYTES = 32;
+const BLOB_META_ROWS = 16;
+
+interface BlobStoreRoot { ids: string[]; cwd?: string }
+/** `role` stays open: an unmapped role is handed on so the adapter records the drop. */
+interface BlobStoreRow { id: string; role: string; message: { content: ContentBlock[]; model?: string } }
+
+function blobBuffer(value: unknown): Buffer {
+  if (value instanceof Uint8Array) return Buffer.from(value.buffer, value.byteOffset, value.byteLength);
+  if (typeof value === "string") return Buffer.from(value, "utf8");
+  throw new NativeInputError("Unsupported Cursor blob-store value: expected text or a blob.");
+}
+
+function blobVarint(buffer: Buffer, offset: number): [number, number] {
+  let value = 0;
+  let shift = 0;
+  for (let index = offset; index < buffer.length; index++) {
+    const byte = buffer[index] as number;
+    value += (byte & 0x7f) * 2 ** shift;
+    if ((byte & 0x80) === 0) return [value, index + 1];
+    shift += 7;
+    if (shift > 56) break;
+  }
+  throw new NativeInputError("Malformed Cursor blob-store root: truncated or oversized varint.");
+}
+
+/** Skip unknown fields by wire type so a field Cursor adds later cannot break the walk. */
+function parseBlobStoreRoot(buffer: Buffer): BlobStoreRoot {
+  const ids: string[] = [];
+  let cwd: string | undefined;
+  let offset = 0;
+  while (offset < buffer.length) {
+    const [tag, afterTag] = blobVarint(buffer, offset);
+    const field = tag >>> 3;
+    const wire = tag & 7;
+    offset = afterTag;
+    if (wire === 2) {
+      const [length, afterLength] = blobVarint(buffer, offset);
+      const end = afterLength + length;
+      if (end > buffer.length) throw new NativeInputError("Malformed Cursor blob-store root: field length exceeds the blob.");
+      if (field === BLOB_MESSAGE_FIELD) {
+        if (length !== BLOB_ID_BYTES) throw new NativeInputError("Unsupported Cursor blob-store root: message ID is not 32 bytes.");
+        if (ids.length >= MAX_NATIVE_RECORDS) throw new NativeInputError("Cursor session exceeds the native record limit.");
+        ids.push(buffer.subarray(afterLength, end).toString("hex"));
+      } else if (field === BLOB_WORKSPACE_FIELD && cwd === undefined) {
+        const uri = buffer.subarray(afterLength, end).toString("utf8");
+        // A workspace URI is metadata; a malformed one must not fail the transcript.
+        if (uri.startsWith("file://")) { try { cwd = fileURLToPath(uri); } catch { /* ignored */ } }
+      }
+      offset = end;
+    } else if (wire === 0) offset = blobVarint(buffer, offset)[1];
+    else if (wire === 5) offset += 4;
+    else if (wire === 1) offset += 8;
+    else throw new NativeInputError("Unsupported Cursor blob-store root wire type.");
+  }
+  if (offset !== buffer.length) throw new NativeInputError("Malformed Cursor blob-store root: trailing bytes.");
+  return { ids, ...(cwd ? { cwd } : {}) };
+}
+
+function hasBlobStore(db: Database): boolean {
+  const tables = new Set((db.query("SELECT name FROM sqlite_schema WHERE type = 'table'").all() as { name: string }[])
+    .map((table) => table.name));
+  if (!tables.has("blobs") || !tables.has("meta")) return false;
+  const columnsOf = (table: string) => new Set((db.query("SELECT lower(name) AS name FROM pragma_table_xinfo(?)").all(table) as { name: string }[])
+    .map((column) => column.name));
+  const blobs = columnsOf("blobs");
+  const meta = columnsOf("meta");
+  if (!blobs.has("id") || !blobs.has("data") || !meta.has("key") || !meta.has("value")) {
+    throw new NativeInputError("Unsupported Cursor blob-store schema: missing id/data or key/value column.");
+  }
+  return true;
+}
+
+/**
+ * Cursor stores the meta row as hex-encoded ASCII rather than raw bytes, unlike
+ * the message blobs. Decode that when it is present and accept plain JSON too, so
+ * the reader keeps working if Cursor drops the extra encoding.
+ */
+function blobStoreJson(value: unknown): unknown {
+  const text = blobBuffer(value).toString("utf8").trim();
+  const decoded = /^(?:[0-9a-fA-F]{2})+$/.test(text) ? Buffer.from(text, "hex").toString("utf8") : text;
+  try { return JSON.parse(decoded); } catch { return undefined; }
+}
+
+/** The first meta row naming both an agent and a root blob; other rows are ignored. */
+function blobStoreMeta(db: Database): Record<string, unknown> | undefined {
+  const rows = db.query("SELECT CAST(value AS BLOB) AS value FROM meta LIMIT ?").all(BLOB_META_ROWS) as { value: unknown }[];
+  for (const row of rows) {
+    const value = blobStoreJson(row.value);
+    if (object(value) && safeNativeId(value.agentId) && safeNativeId(value.latestRootBlobId)) return value;
+  }
+  return undefined;
+}
+
+function blobData(db: Database, id: string): Buffer | undefined {
+  const row = db.query("SELECT CAST(data AS BLOB) AS data FROM blobs WHERE id = ?").get(id) as { data: unknown } | null;
+  return row ? blobBuffer(row.data) : undefined;
+}
+
+function blobModel(block: Record<string, unknown>): string | undefined {
+  if (!object(block.providerOptions) || !object(block.providerOptions.cursor)) return;
+  const name = block.providerOptions.cursor.modelName;
+  return typeof name === "string" && name ? name : undefined;
+}
+
+/** Prefer the flat result; fall back to the block list Cursor writes alongside it. */
+function blobResult(block: Record<string, unknown>): unknown {
+  if (block.result !== undefined && block.result !== null) return block.result;
+  return Array.isArray(block.experimental_content) ? block.experimental_content : "";
+}
+
+/**
+ * Rename Cursor's blocks to the ones the trajectory adapter decodes. A
+ * `redacted-reasoning` block holds only provider-encrypted bytes, so it is passed
+ * through unchanged rather than given invented plaintext: the adapter then records
+ * the drop instead of this reader hiding it.
+ *
+ * One unusable block drops itself, never the session. A tool call without the ID
+ * that pairs it to its result cannot be represented, but refusing the whole store
+ * over it would lose every other message in the file — the same reasoning that
+ * makes a non-message blob a reported skip rather than a fatal read.
+ */
+function blobStoreContent(blocks: unknown[], diagnostics: Diagnostic[]): { content: ContentBlock[]; model?: string } {
+  const content: ContentBlock[] = [];
+  let model: string | undefined;
+  for (const block of blocks) {
+    if (!object(block)) {
+      diagnostics.push({ code: "noise_record_dropped", message: "Skipped a Cursor content block that is not an object." });
+      continue;
+    }
+    model ??= blobModel(block);
+    if (block.type === "text") {
+      if (typeof block.text === "string" && block.text.length) content.push({ type: "text", text: block.text });
+    } else if (block.type === "reasoning") {
+      if (typeof block.text === "string" && block.text.length) content.push({ type: "thinking", thinking: block.text });
+    } else if (block.type === "tool-call") {
+      // A call ID pairs a call with its result; it is never a path, so it is not
+      // held to safeNativeId — Cursor writes IDs containing separators.
+      if (typeof block.toolCallId !== "string" || !block.toolCallId || typeof block.toolName !== "string" || !block.toolName) {
+        diagnostics.push({ code: "noise_record_dropped", message: "Skipped a Cursor tool call with no native call ID or tool name." });
+        continue;
+      }
+      content.push({ type: "tool_use", id: block.toolCallId, name: block.toolName, input: block.args ?? {} });
+    } else if (block.type === "tool-result") {
+      if (typeof block.toolCallId !== "string" || !block.toolCallId) {
+        diagnostics.push({ code: "noise_record_dropped", message: "Skipped a Cursor tool result with no native call ID." });
+        continue;
+      }
+      content.push({ type: "tool_result", tool_use_id: block.toolCallId, content: blobResult(block) });
+    } else {
+      content.push(block);
+    }
+  }
+  return { content, ...(model ? { model } : {}) };
+}
+
+function discoverBlobStore(path: string, options: NativeDiscoveryOptions): DiscoveredSession[] {
+  return withCursorDb(path, (db) => {
+    if (!hasBlobStore(db)) {
+      options.onDiagnostic?.({ code: "invalid_metadata", sourcePath: path, message: "Unsupported Cursor blob-store database schema." });
+      return [];
+    }
+    const meta = blobStoreMeta(db);
+    if (!meta) {
+      options.onDiagnostic?.({ code: "invalid_metadata", sourcePath: path, message: "Cursor blob store has no agent metadata row." });
+      return [];
+    }
+    const id = meta.agentId as string;
+    if (!blobData(db, meta.latestRootBlobId as string)) {
+      options.onDiagnostic?.({ code: "incomplete_evidence", sourcePath: path, message: "Cursor blob store is missing its root blob." });
+      return [];
+    }
+    const title = typeof meta.name === "string" && meta.name ? meta.name : undefined;
+    return [{ id, source: "cursor", path, native: { kind: "cursor-blobstore" },
+      updatedAt: lstatSync(path).mtime.toISOString(),
+      ...(title !== undefined ? { title } : {}) }];
+  });
+}
+
+/**
+ * Cursor writes tool results as their own `tool` role. The canonical shape keeps
+ * a tool result on the user turn that carries it, so the role is mapped here; the
+ * blob hash is the record ID, which the store proves unique within a root.
+ */
+function readBlobStore(db: Database, id: string, limit: number): NativeTranscript {
+  if (!hasBlobStore(db)) throw new NativeInputError("Missing Cursor blob-store tables.");
+  const meta = blobStoreMeta(db);
+  if (!meta) throw new NativeInputError("Missing Cursor blob-store agent metadata.");
+  if (meta.agentId !== id) throw new NativeInputError("Conflicting Cursor native session ID.");
+  const rootData = blobData(db, meta.latestRootBlobId as string);
+  if (!rootData) throw new NativeInputError("Missing Cursor blob-store root blob.");
+  const root = parseBlobStoreRoot(rootData);
+  const lines: string[] = [];
+  const diagnostics: Diagnostic[] = [];
+  let bytes = 0;
+  for (const blobId of root.ids) {
+    const data = blobData(db, blobId);
+    // A root can reference a blob the store no longer holds, and the same store
+    // holds non-message blobs (out-of-line file bodies, and protobuf records in
+    // the ACP layout). Neither is corruption, so both are dropped through the
+    // reader's own diagnostics rather than failing the whole session.
+    if (!data) {
+      diagnostics.push({ code: "noise_record_dropped", message: "Cursor root references a blob the store no longer holds." });
+      continue;
+    }
+    bytes += data.length;
+    if (bytes > limit) throw new NativeInputError("Cursor session exceeds the native byte limit.");
+    let value: unknown;
+    try { value = JSON.parse(data.toString("utf8")); } catch {
+      diagnostics.push({ code: "noise_record_dropped", message: "Skipped a Cursor blob that is not JSON." });
+      continue;
+    }
+    if (!object(value) || typeof value.role !== "string" || !value.role) {
+      diagnostics.push({ code: "noise_record_dropped", message: "Skipped a Cursor blob with no role." });
+      continue;
+    }
+    const raw = value.content;
+    const projected = Array.isArray(raw) ? blobStoreContent(raw, diagnostics)
+      : { content: typeof raw === "string" && raw.length ? [{ type: "text", text: raw } as ContentBlock] : [] };
+    if (!projected.content.length) {
+      diagnostics.push({ code: "noise_record_dropped", message: "Skipped a Cursor message whose content projected to nothing." });
+      continue;
+    }
+    const row: BlobStoreRow = { id: blobId, role: value.role === "tool" ? "user" : value.role,
+      message: { content: projected.content, ...(projected.model ? { model: projected.model } : {}) } };
+    const line = JSON.stringify(row);
+    bytes += Buffer.byteLength(line) + 1;
+    if (bytes > limit) throw new NativeInputError("Cursor transcript exceeds the native byte limit.");
+    lines.push(line);
+  }
+  const title = typeof meta.name === "string" && meta.name ? meta.name : undefined;
+  const startedAt = nativeTime(meta.createdAt);
+  return { transcript: lines.length ? lines.join("\n") + "\n" : "",
+    ...(title !== undefined ? { title } : {}), ...(root.cwd ? { cwd: root.cwd } : {}),
+    ...(startedAt ? { startedAt } : {}), ...(diagnostics.length ? { diagnostics } : {}) };
+}
+
+export function readCursorSession(item: DiscoveredSession, options: NativeReadOptions = {}): NativeTranscript {
+  const limit = nativeByteLimit(options);
+  if (!item.native) return { transcript: readBoundedText(item.path, limit) };
+  if (!safeNativeId(item.id)) throw new NativeInputError("Unsupported Cursor native session.");
+  if (item.native.kind === "cursor-blobstore") return withCursorDb(item.path, (db) => readBlobStore(db, item.id, limit));
+  if (item.native.kind !== "cursor-sqlite") throw new NativeInputError("Unsupported Cursor native session.");
+  return withCursorDb(item.path, (db) => {
+    const budget: ReadBudget = { bytes: 0, rows: 0, limit };
+    const composer = hasTable(db, "cursorDiskKV") ? readJsonRow(db, `${COMPOSER_PREFIX}${item.id}`, budget) : undefined;
+    if (!composer) return readLegacySession(db, item.id, budget);
+    if (composer.composerId != null && composer.composerId !== item.id) throw new NativeInputError("Conflicting Cursor native session ID.");
+    if (!Array.isArray(composer.fullConversationHeadersOnly)) throw new NativeInputError("Unsupported Cursor conversation layout.");
+    if (composer.fullConversationHeadersOnly.length === 0 && object(composer.conversationMap) && Object.keys(composer.conversationMap).length) {
+      throw new NativeInputError("Incomplete Cursor conversation: inline messages have no ordered headers.");
+    }
+    if (composer.fullConversationHeadersOnly.length >= MAX_NATIVE_RECORDS) throw new NativeInputError("Cursor session exceeds the native record limit.");
+    const lines: string[] = [];
+    const timestamps: string[] = [];
+    const ids = new Set<string>();
+    let outputBytes = 0;
+    for (const header of composer.fullConversationHeadersOnly) {
+      if (!object(header) || !safeNativeId(header.bubbleId)) throw new NativeInputError("Incomplete Cursor header: missing native bubble ID.");
+      if (ids.has(header.bubbleId)) throw new NativeInputError("Duplicate Cursor native bubble ID.");
+      ids.add(header.bubbleId);
+      const inline = object(composer.conversationMap) && Object.hasOwn(composer.conversationMap, header.bubbleId)
+        ? composer.conversationMap[header.bubbleId] : undefined;
+      const bubble = inline !== undefined ? inline : readJsonRow(db, `bubbleId:${item.id}:${header.bubbleId}`, budget);
+      if (!bubble) throw new NativeInputError("Missing referenced Cursor bubble; transcript is incomplete.");
+      if (!object(bubble)) throw new NativeInputError("Invalid Cursor inline conversation bubble.");
+      const line = JSON.stringify(bubbleRow(bubble, header.bubbleId, header.type));
+      outputBytes += Buffer.byteLength(line) + 1;
+      if (outputBytes > limit) throw new NativeInputError("Cursor transcript exceeds the native byte limit.");
+      lines.push(line);
+      const time = nativeTime(bubble.createdAt);
+      if (time) timestamps.push(time);
+    }
+    const cwd = typeof composer.cwd === "string" ? composer.cwd : typeof composer.repoPath === "string" ? composer.repoPath : undefined;
+    const model = typeof composer.model === "string" ? composer.model : undefined;
+    const title = typeof composer.name === "string" ? composer.name : undefined;
+    const startedAt = nativeTime(composer.createdAt) ?? timestamps[0];
+    const endedAt = [nativeTime(composer.lastUpdatedAt), ...timestamps].filter((time): time is string => !!time).sort().at(-1);
+    return { transcript: lines.length ? lines.join("\n") + "\n" : "",
+      ...(title !== undefined ? { title } : {}),
+      ...(cwd ? { cwd } : {}), ...(model ? { model } : {}), ...(startedAt ? { startedAt } : {}), ...(endedAt ? { endedAt } : {}),
+    };
+  });
+}