@tracebench/adapter-cursor 0.2.2 → 0.2.5

package/src/db-read.ts

@@ -0,0 +1,199 @@
+// Read Composer sessions from Cursor's global state.vscdb.
+
+import { statSync } from 'node:fs';
+import { SqliteDatabase } from '@tracebench/core';
+import type {
+  ComposerDataRow,
+  ComposerHeaderEntry,
+  ConversationHeader,
+  CursorBubble,
+} from './db-types.js';
+import { snapshotCursorDb, releaseDbSnapshot } from './db-snapshot.js';
+
+export interface ComposerListEntry {
+  composerId: string;
+  name: string | null;
+  subtitle: string | null;
+  projectPath: string | null;
+  createdAtMs: number | null;
+  lastUpdatedAtMs: number | null;
+  unifiedMode: string | null;
+  modelName: string | null;
+  bubbleCount: number;
+  /** Number of bubbles listed in fullConversationHeadersOnly (may be 0 for agent sessions). */
+  headerBubbleCount: number;
+}
+
+function parseJson<T>(raw: string | Buffer | null | undefined): T | null {
+  if (raw == null) return null;
+  const s = typeof raw === 'string' ? raw : raw.toString('utf8');
+  if (!s) return null;
+  try {
+    return JSON.parse(s) as T;
+  } catch {
+    return null;
+  }
+}
+
+function workspacePath(
+  ws?: { uri?: { fsPath?: string; path?: string } },
+): string | null {
+  return ws?.uri?.fsPath ?? ws?.uri?.path ?? null;
+}
+
+function openReadonly(dbPath: string) {
+  return new SqliteDatabase(dbPath, { readonly: true, fileMustExist: true });
+}
+
+/** List composers that have at least one stored bubble. */
+export function listComposersWithBubbles(dbPath: string): ComposerListEntry[] {
+  const snap = snapshotCursorDb(dbPath);
+  if (!snap) return [];
+
+  try {
+    const db = openReadonly(snap.dbPath);
+
+    const headersRaw = db
+      .prepare('SELECT value FROM ItemTable WHERE key = ?')
+      .get('composer.composerHeaders') as { value: string } | undefined;
+    const headers = parseJson<{ allComposers?: ComposerHeaderEntry[] }>(
+      headersRaw?.value,
+    );
+    const headerById = new Map<string, ComposerHeaderEntry>();
+    for (const h of headers?.allComposers ?? []) {
+      if (h.composerId) headerById.set(h.composerId, h);
+    }
+
+    const bubbleCounts = new Map<string, number>();
+    const rows = db
+      .prepare(
+        `SELECT key FROM cursorDiskKV WHERE key LIKE 'bubbleId:%'`,
+      )
+      .all() as { key: string }[];
+    for (const { key } of rows) {
+      const parts = key.split(':');
+      if (parts.length < 3) continue;
+      const composerId = parts[1]!;
+      bubbleCounts.set(composerId, (bubbleCounts.get(composerId) ?? 0) + 1);
+    }
+
+    const composerIds = [...bubbleCounts.keys()];
+    const out: ComposerListEntry[] = [];
+
+    const dataStmt = db.prepare(
+      'SELECT value FROM cursorDiskKV WHERE key = ?',
+    );
+
+    for (const composerId of composerIds) {
+      const dataRow = dataStmt.get(`composerData:${composerId}`) as
+        | { value: string }
+        | undefined;
+      const data = parseJson<ComposerDataRow>(dataRow?.value);
+      const header = headerById.get(composerId);
+
+      const name =
+        data?.name ?? header?.name ?? header?.subtitle ?? data?.subtitle ?? null;
+      const projectPath =
+        workspacePath(data?.workspaceIdentifier) ??
+        workspacePath(header?.workspaceIdentifier);
+
+      out.push({
+        composerId,
+        name: name ?? null,
+        subtitle: data?.subtitle ?? header?.subtitle ?? null,
+        projectPath,
+        createdAtMs: data?.createdAt ?? header?.createdAt ?? null,
+        lastUpdatedAtMs: data?.lastUpdatedAt ?? header?.lastUpdatedAt ?? null,
+        unifiedMode: data?.unifiedMode ?? header?.unifiedMode ?? null,
+        modelName: data?.modelConfig?.modelName ?? null,
+        bubbleCount: bubbleCounts.get(composerId) ?? 0,
+        headerBubbleCount: data?.fullConversationHeadersOnly?.length ?? 0,
+      });
+    }
+
+    db.close();
+    out.sort((a, b) => (b.lastUpdatedAtMs ?? 0) - (a.lastUpdatedAtMs ?? 0));
+    return out;
+  } finally {
+    releaseDbSnapshot(snap);
+  }
+}
+
+export interface LoadedComposer {
+  composerId: string;
+  data: ComposerDataRow | null;
+  headers: ConversationHeader[];
+  bubbles: CursorBubble[];
+}
+
+export function loadComposerFromDb(
+  dbPath: string,
+  composerId: string,
+): LoadedComposer | null {
+  const snap = snapshotCursorDb(dbPath);
+  if (!snap) return null;
+
+  try {
+    const db = openReadonly(snap.dbPath);
+
+    const dataRow = db
+      .prepare('SELECT value FROM cursorDiskKV WHERE key = ?')
+      .get(`composerData:${composerId}`) as { value: string } | undefined;
+    const data = parseJson<ComposerDataRow>(dataRow?.value);
+
+    const headerList = data?.fullConversationHeadersOnly ?? [];
+    const bubbles: CursorBubble[] = [];
+
+    const bubbleStmt = db.prepare(
+      'SELECT value FROM cursorDiskKV WHERE key = ?',
+    );
+    const prefix = `bubbleId:${composerId}:`;
+
+    if (headerList.length > 0) {
+      for (const h of headerList) {
+        const row = bubbleStmt.get(`${prefix}${h.bubbleId}`) as
+          | { value: string }
+          | undefined;
+        const bubble = parseJson<CursorBubble>(row?.value);
+        if (bubble) bubbles.push(bubble);
+      }
+    } else {
+      const all = db
+        .prepare(
+          `SELECT key, value FROM cursorDiskKV WHERE key LIKE ?`,
+        )
+        .all(`${prefix}%`) as { key: string; value: string }[];
+      for (const row of all) {
+        const bubble = parseJson<CursorBubble>(row.value);
+        if (bubble) bubbles.push(bubble);
+      }
+      bubbles.sort((a, b) => {
+        const ta = a.createdAt ? Date.parse(a.createdAt) : 0;
+        const tb = b.createdAt ? Date.parse(b.createdAt) : 0;
+        return ta - tb;
+      });
+    }
+
+    db.close();
+
+    if (bubbles.length === 0 && !data) return null;
+
+    return {
+      composerId,
+      data,
+      headers: headerList,
+      bubbles,
+    };
+  } finally {
+    releaseDbSnapshot(snap);
+  }
+}
+
+/** DB mtime for incremental indexing (main file only). */
+export function cursorDbMtimeMs(dbPath: string): number {
+  try {
+    return statSync(dbPath).mtimeMs;
+  } catch {
+    return 0;
+  }
+}

package/src/db-snapshot.ts

@@ -0,0 +1,41 @@
+// Copy Cursor's state.vscdb (+ WAL sidecars) for consistent reads while Cursor is running.
+
+import { copyFileSync, existsSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, join } from 'node:path';
+
+export interface DbSnapshot {
+  /** Path to the copied main DB file (inside a temp dir). */
+  dbPath: string;
+  /** Temp directory holding the snapshot; call `releaseDbSnapshot` when done. */
+  tempDir: string;
+}
+
+/**
+ * Snapshot `state.vscdb` (and `-wal`/`-shm` when present) into a temp directory.
+ * Returns null when the main DB file does not exist.
+ */
+export function snapshotCursorDb(mainDbPath: string): DbSnapshot | null {
+  if (!existsSync(mainDbPath)) return null;
+
+  const tempDir = mkdtempSync(join(tmpdir(), 'tracebench-cursor-db-'));
+  const base = basename(mainDbPath);
+  const dir = join(mainDbPath, '..');
+
+  copyFileSync(mainDbPath, join(tempDir, base));
+  const wal = join(dir, `${base}-wal`);
+  const shm = join(dir, `${base}-shm`);
+  if (existsSync(wal)) copyFileSync(wal, join(tempDir, `${base}-wal`));
+  if (existsSync(shm)) copyFileSync(shm, join(tempDir, `${base}-shm`));
+
+  return { dbPath: join(tempDir, base), tempDir };
+}
+
+export function releaseDbSnapshot(snapshot: DbSnapshot | null): void {
+  if (!snapshot) return;
+  try {
+    rmSync(snapshot.tempDir, { recursive: true, force: true });
+  } catch {
+    // ignore cleanup failures
+  }
+}

package/src/db-types.ts

@@ -0,0 +1,60 @@
+export interface ComposerHeaderEntry {
+  type?: string;
+  composerId: string;
+  name?: string;
+  subtitle?: string;
+  lastUpdatedAt?: number;
+  createdAt?: number;
+  unifiedMode?: string;
+  isArchived?: boolean;
+  workspaceIdentifier?: {
+    uri?: { fsPath?: string; path?: string };
+  };
+}
+
+export interface ConversationHeader {
+  bubbleId: string;
+  type: number; // 1 = user, 2 = assistant
+}
+
+export interface ComposerDataRow {
+  composerId: string;
+  name?: string;
+  subtitle?: string;
+  createdAt?: number;
+  lastUpdatedAt?: number;
+  unifiedMode?: string;
+  status?: string;
+  fullConversationHeadersOnly?: ConversationHeader[];
+  workspaceIdentifier?: {
+    uri?: { fsPath?: string; path?: string };
+  };
+  modelConfig?: { modelName?: string };
+  isArchived?: boolean;
+  isDraft?: boolean;
+}
+
+export interface CursorBubble {
+  bubbleId?: string;
+  type?: number;
+  text?: string;
+  richText?: string;
+  createdAt?: string;
+  capabilityType?: number;
+  thinking?: { text?: string };
+  thinkingDurationMs?: number;
+  modelInfo?: { modelName?: string };
+  tokenCount?: {
+    inputTokens?: number;
+    outputTokens?: number;
+  };
+  toolFormerData?: {
+    toolCallId?: string;
+    name?: string;
+    status?: string;
+    rawArgs?: string;
+    params?: string;
+    result?: string;
+    additionalData?: Record<string, unknown>;
+  };
+}

package/src/db-uri.ts

@@ -0,0 +1,25 @@
+// Virtual paths for Composer DB sessions (indexed by tracebench as raw_path).
+
+const PREFIX = 'cursor-db:';
+
+/** Stable raw_path for a Composer session loaded from SQLite. */
+export function composerDbUri(composerId: string, globalDbPath: string): string {
+  return `${PREFIX}${composerId}@${globalDbPath}`;
+}
+
+export function parseComposerDbUri(
+  rawPath: string,
+): { composerId: string; globalDbPath: string } | null {
+  if (!rawPath.startsWith(PREFIX)) return null;
+  const rest = rawPath.slice(PREFIX.length);
+  const at = rest.lastIndexOf('@');
+  if (at <= 0) return null;
+  return {
+    composerId: rest.slice(0, at),
+    globalDbPath: rest.slice(at + 1),
+  };
+}
+
+export function isComposerDbUri(rawPath: string): boolean {
+  return rawPath.startsWith(PREFIX);
+}

package/src/discover-db.ts

@@ -0,0 +1,33 @@
+// Discover Cursor Composer sessions from global state.vscdb.
+
+import { defaultCursorGlobalDbPath } from './paths.js';
+import { listComposersWithBubbles, cursorDbMtimeMs } from './db-read.js';
+import { composerDbUri } from './db-uri.js';
+
+export interface DiscoveredComposerSession {
+  session_id: string;
+  file_path: string;
+  global_db_path: string;
+  project_path: string | null;
+  name: string | null;
+  size: number;
+  mtime_ms: number;
+}
+
+export function discoverComposerSessions(
+  globalDbPath?: string,
+): DiscoveredComposerSession[] {
+  const dbPath = globalDbPath ?? defaultCursorGlobalDbPath();
+  const dbMtime = cursorDbMtimeMs(dbPath);
+  const composers = listComposersWithBubbles(dbPath);
+
+  return composers.map((c) => ({
+    session_id: c.composerId,
+    file_path: composerDbUri(c.composerId, dbPath),
+    global_db_path: dbPath,
+    project_path: c.projectPath,
+    name: c.name,
+    size: c.bubbleCount,
+    mtime_ms: c.lastUpdatedAtMs ?? dbMtime,
+  }));
+}

package/src/discover.test.ts

@@ -22,13 +22,15 @@ describe('discoverSessions', () => {
     writeFileSync(nested, '{"role":"user","message":{"content":[]}}\n');
     writeFileSync(subagent, '{"role":"user","message":{"content":[]}}\n');
 
-    const found = discoverSessions(root);
+    const found = discoverSessions({ projectsRoot: root, globalDbPath: false });
     const ids = found.map((f) => f.session_id).sort();
     expect(ids).toEqual(['sess-main', 'sess-sub']);
     expect(found.every((f) => f.encoded_project_dir === 'Users-me-testproj')).toBe(true);
   });
 
   it('returns empty when root is missing', () => {
-    expect(discoverSessions('/nonexistent/tracebench-cursor-root')).toEqual([]);
+    expect(
+      discoverSessions({ projectsRoot: '/nonexistent/tracebench-cursor-root', globalDbPath: false }),
+    ).toEqual([]);
   });
 });

package/src/discover.ts

@@ -9,6 +9,7 @@
 import { readdirSync, statSync } from 'node:fs';
 import { join, basename } from 'node:path';
 import { defaultCursorProjectsRoot } from './paths.js';
+import { discoverComposerSessions } from './discover-db.js';
 
 export interface DiscoveredCursorSession {
   session_id: string;
@@ -16,6 +17,8 @@ export interface DiscoveredCursorSession {
   encoded_project_dir: string;
   size: number;
   mtime_ms: number;
+  /** Present when loaded from Composer SQLite instead of JSONL. */
+  source?: 'jsonl' | 'composer_db';
 }
 
 export { defaultCursorProjectsRoot as defaultProjectsRoot };
@@ -56,8 +59,14 @@ function walkJsonl(
   }
 }
 
-export function discoverSessions(root?: string): DiscoveredCursorSession[] {
-  const base = root ?? defaultCursorProjectsRoot();
+export interface DiscoverSessionsOptions {
+  /** Override ~/.cursor/projects */
+  projectsRoot?: string;
+  /** Override global state.vscdb path; set to false to skip DB discovery. */
+  globalDbPath?: string | false;
+}
+
+function discoverJsonlSessions(base: string): DiscoveredCursorSession[] {
   const out: DiscoveredCursorSession[] = [];
   let projectDirs: string[];
   try {
@@ -71,6 +80,49 @@ export function discoverSessions(root?: string): DiscoveredCursorSession[] {
     const transcriptsDir = join(base, dir, 'agent-transcripts');
     walkJsonl(transcriptsDir, dir, out);
   }
-  out.sort((a, b) => b.mtime_ms - a.mtime_ms);
+  for (const s of out) s.source = 'jsonl';
   return out;
 }
+
+/**
+ * Discover agent-transcript JSONL sessions and Composer DB sessions.
+ * When the same composerId exists in both, the DB entry wins (richer events).
+ */
+export function discoverSessions(
+  rootOrOpts?: string | DiscoverSessionsOptions,
+): DiscoveredCursorSession[] {
+  const opts: DiscoverSessionsOptions =
+    typeof rootOrOpts === 'string' ? { projectsRoot: rootOrOpts } : (rootOrOpts ?? {});
+
+  const base = opts.projectsRoot ?? defaultCursorProjectsRoot();
+  const jsonl = discoverJsonlSessions(base);
+
+  if (opts.globalDbPath === false) {
+    jsonl.sort((a, b) => b.mtime_ms - a.mtime_ms);
+    return jsonl;
+  }
+
+  let dbSessions: DiscoveredCursorSession[] = [];
+  try {
+    dbSessions = discoverComposerSessions(
+      opts.globalDbPath === undefined ? undefined : opts.globalDbPath,
+    ).map((d) => ({
+      session_id: d.session_id,
+      file_path: d.file_path,
+      encoded_project_dir: '',
+      size: d.size,
+      mtime_ms: d.mtime_ms,
+      source: 'composer_db' as const,
+    }));
+  } catch {
+    dbSessions = [];
+  }
+
+  const dbIds = new Set(dbSessions.map((s) => s.session_id));
+  const merged = [
+    ...dbSessions,
+    ...jsonl.filter((s) => !dbIds.has(s.session_id)),
+  ];
+  merged.sort((a, b) => b.mtime_ms - a.mtime_ms);
+  return merged;
+}

package/src/index.ts

@@ -1,5 +1,8 @@
 export const HARNESS_NAME = 'cursor' as const;
+/** JSONL agent-transcript format version. */
 export const FORMAT_VERSION = '2026-q1';
+/** Composer SQLite (state.vscdb) format version. */
+export const FORMAT_VERSION_COMPOSER = '2026-q1-composer';
 
 export {
   defaultCursorProjectsRoot,
@@ -7,7 +10,13 @@ export {
   defaultCursorGlobalDbPath,
   decodeProjectPath,
 } from './paths.js';
-export { defaultProjectsRoot, discoverSessions, type DiscoveredCursorSession } from './discover.js';
+export {
+  defaultProjectsRoot,
+  discoverSessions,
+  type DiscoveredCursorSession,
+  type DiscoverSessionsOptions,
+} from './discover.js';
+export { discoverComposerSessions, type DiscoveredComposerSession } from './discover-db.js';
 export { parseSession, streamSession, type RawCursorEvent } from './parse.js';
 export {
   loadSession,
@@ -15,3 +24,6 @@ export {
   parseTranscriptPath,
   type NormalizeResult,
 } from './normalize.js';
+export { loadComposerSession } from './load-db.js';
+export { normalizeComposerSession, FORMAT_VERSION_DB } from './normalize-db.js';
+export { composerDbUri, parseComposerDbUri, isComposerDbUri } from './db-uri.js';

package/src/load-db.ts

@@ -0,0 +1,25 @@
+import { loadComposerFromDb } from './db-read.js';
+import { parseComposerDbUri } from './db-uri.js';
+import { normalizeComposerSession } from './normalize-db.js';
+import type { NormalizeResult } from './normalize.js';
+
+export async function loadComposerSession(
+  rawPath: string,
+  opts: { formatVersion?: string } = {},
+): Promise<NormalizeResult> {
+  const parsed = parseComposerDbUri(rawPath);
+  if (!parsed) {
+    throw new Error(`not a composer DB path: ${rawPath}`);
+  }
+
+  const loaded = loadComposerFromDb(parsed.globalDbPath, parsed.composerId);
+  if (!loaded) {
+    throw new Error(`composer not found in DB: ${parsed.composerId}`);
+  }
+
+  return normalizeComposerSession(loaded, {
+    rawPath,
+    globalDbPath: parsed.globalDbPath,
+    formatVersion: opts.formatVersion,
+  });
+}

package/src/normalize-db.test.ts

@@ -0,0 +1,88 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { createMinimalCursorDb } from './db-fixture.js';
+import { listComposersWithBubbles, loadComposerFromDb } from './db-read.js';
+import { discoverComposerSessions } from './discover-db.js';
+import { composerDbUri } from './db-uri.js';
+import { loadComposerSession } from './load-db.js';
+import { discoverSessions } from './discover.js';
+
+const COMPOSER_ID = 'aaaa-bbbb-cccc-dddd-eeeeeeeeeeee';
+
+let dbPath: string;
+let tempDir: string;
+
+beforeAll(() => {
+  tempDir = mkdtempSync(join(tmpdir(), 'tb-cursor-db-fixture-'));
+  dbPath = join(tempDir, 'state.vscdb');
+  createMinimalCursorDb(dbPath);
+});
+
+afterAll(() => {
+  rmSync(tempDir, { recursive: true, force: true });
+});
+
+describe('Composer DB reader', () => {
+  it('lists composers with bubbles', () => {
+    const list = listComposersWithBubbles(dbPath);
+    expect(list.length).toBe(1);
+    expect(list[0]!.composerId).toBe(COMPOSER_ID);
+    expect(list[0]!.bubbleCount).toBe(3);
+    expect(list[0]!.projectPath).toBe('/Users/me/code/fixture');
+  });
+
+  it('loads ordered bubbles from fullConversationHeadersOnly', () => {
+    const loaded = loadComposerFromDb(dbPath, COMPOSER_ID);
+    expect(loaded).not.toBeNull();
+    expect(loaded!.bubbles.length).toBe(3);
+    expect(loaded!.bubbles[0]!.type).toBe(1);
+    expect(loaded!.bubbles[1]!.capabilityType).toBe(30);
+    expect(loaded!.bubbles[2]!.toolFormerData?.toolCallId).toBe('tool_fixture_call_001');
+  });
+});
+
+describe('normalize Composer DB session', () => {
+  it('emits tool_call + tool_result with stable call id', async () => {
+    const uri = composerDbUri(COMPOSER_ID, dbPath);
+    const { session, events } = await loadComposerSession(uri);
+    expect(session.harness).toBe('cursor');
+    expect(session.session_id).toBe(COMPOSER_ID);
+    expect(session.model).toBe('composer-2.5');
+    expect(session.title).toMatch(/Summarize the fixture/);
+
+    const toolCall = events.find((e) => e.event_type === 'tool_call');
+    const toolResult = events.find((e) => e.event_type === 'tool_result');
+    expect(toolCall).toBeDefined();
+    expect(toolResult).toBeDefined();
+    expect(toolCall!.event_id).toBe('tool_fixture_call_001');
+    expect(toolResult!.parent_event_id).toBe('tool_fixture_call_001');
+    expect(toolCall!.tool.name).toBe('Read');
+    expect(toolResult!.tool.output).toContain('Fixture');
+  });
+
+  it('emits thinking events from capabilityType 30 bubbles', async () => {
+    const { events } = await loadComposerSession(composerDbUri(COMPOSER_ID, dbPath));
+    expect(events.some((e) => e.event_type === 'thinking')).toBe(true);
+  });
+});
+
+describe('discover merge', () => {
+  it('prefers DB session over JSONL with same composer id', () => {
+    const merged = discoverSessions({
+      projectsRoot: join(tempDir, 'empty-projects'),
+      globalDbPath: dbPath,
+    });
+    const match = merged.find((s) => s.session_id === COMPOSER_ID);
+    expect(match).toBeDefined();
+    expect(match!.source).toBe('composer_db');
+    expect(match!.file_path).toContain('cursor-db:');
+  });
+
+  it('discovers composer sessions via discoverComposerSessions', () => {
+    const dbOnly = discoverComposerSessions(dbPath);
+    expect(dbOnly.length).toBe(1);
+    expect(dbOnly[0]!.session_id).toBe(COMPOSER_ID);
+  });
+});