@tracebench/adapter-cursor 0.2.0

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@tracebench/adapter-cursor",
+  "version": "0.2.0",
+  "description": "Tracebench adapter for Cursor agent transcripts (~/.cursor/projects/**/agent-transcripts/**/*.jsonl).",
+  "license": "Apache-2.0",
+  "author": "Skandesh",
+  "homepage": "https://github.com/Skandesh/tracebench",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Skandesh/tracebench.git",
+    "directory": "packages/adapter-cursor"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@tracebench/core": "0.2.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}

package/src/discover.test.ts

@@ -0,0 +1,34 @@
+import { describe, it, expect } from 'vitest';
+import { mkdtempSync, mkdirSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { discoverSessions } from './discover.js';
+
+describe('discoverSessions', () => {
+  it('finds nested and subagent jsonl files', () => {
+    const root = mkdtempSync(join(tmpdir(), 'tb-cursor-discover-'));
+    const project = join(root, 'Users-me-testproj');
+    const nested = join(project, 'agent-transcripts', 'sess-main', 'sess-main.jsonl');
+    const subagent = join(
+      project,
+      'agent-transcripts',
+      'sess-main',
+      'subagents',
+      'sess-sub.jsonl',
+    );
+    mkdirSync(join(project, 'agent-transcripts', 'sess-main', 'subagents'), {
+      recursive: true,
+    });
+    writeFileSync(nested, '{"role":"user","message":{"content":[]}}\n');
+    writeFileSync(subagent, '{"role":"user","message":{"content":[]}}\n');
+
+    const found = discoverSessions(root);
+    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([]);
+  });
+});

package/src/discover.ts

@@ -0,0 +1,76 @@
+// Discover Cursor agent transcripts on disk.
+//
+// Layout:
+//   ~/.cursor/projects/<sanitized-path>/agent-transcripts/
+//     <session-uuid>.jsonl                         (flat)
+//     <session-uuid>/<session-uuid>.jsonl          (nested)
+//     <parent-uuid>/subagents/<subagent-uuid>.jsonl
+
+import { readdirSync, statSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import { defaultCursorProjectsRoot } from './paths.js';
+
+export interface DiscoveredCursorSession {
+  session_id: string;
+  file_path: string;
+  encoded_project_dir: string;
+  size: number;
+  mtime_ms: number;
+}
+
+export { defaultCursorProjectsRoot as defaultProjectsRoot };
+
+function walkJsonl(
+  dir: string,
+  encodedProjectDir: string,
+  out: DiscoveredCursorSession[],
+): void {
+  let entries: import('node:fs').Dirent[];
+  try {
+    entries = readdirSync(dir, { withFileTypes: true }) as import('node:fs').Dirent[];
+  } catch {
+    return;
+  }
+  for (const ent of entries) {
+    const name = String(ent.name);
+    const p = join(dir, name);
+    if (ent.isDirectory()) {
+      walkJsonl(p, encodedProjectDir, out);
+      continue;
+    }
+    if (!name.endsWith('.jsonl')) continue;
+    let st;
+    try {
+      st = statSync(p);
+    } catch {
+      continue;
+    }
+    const sessionId = basename(name, '.jsonl');
+    out.push({
+      session_id: sessionId,
+      file_path: p,
+      encoded_project_dir: encodedProjectDir,
+      size: st.size,
+      mtime_ms: st.mtimeMs,
+    });
+  }
+}
+
+export function discoverSessions(root?: string): DiscoveredCursorSession[] {
+  const base = root ?? defaultCursorProjectsRoot();
+  const out: DiscoveredCursorSession[] = [];
+  let projectDirs: string[];
+  try {
+    projectDirs = readdirSync(base, { withFileTypes: true })
+      .filter((d) => d.isDirectory())
+      .map((d) => d.name);
+  } catch {
+    return out;
+  }
+  for (const dir of projectDirs) {
+    const transcriptsDir = join(base, dir, 'agent-transcripts');
+    walkJsonl(transcriptsDir, dir, out);
+  }
+  out.sort((a, b) => b.mtime_ms - a.mtime_ms);
+  return out;
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+export const HARNESS_NAME = 'cursor' as const;
+export const FORMAT_VERSION = '2026-q1';
+
+export {
+  defaultCursorProjectsRoot,
+  defaultCursorUserDataDir,
+  defaultCursorGlobalDbPath,
+  decodeProjectPath,
+} from './paths.js';
+export { defaultProjectsRoot, discoverSessions, type DiscoveredCursorSession } from './discover.js';
+export { parseSession, streamSession, type RawCursorEvent } from './parse.js';
+export {
+  loadSession,
+  normalizeSession,
+  parseTranscriptPath,
+  type NormalizeResult,
+} from './normalize.js';

package/src/normalize.test.ts

@@ -0,0 +1,71 @@
+import { describe, it, expect } from 'vitest';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadSession, normalizeSession, parseTranscriptPath } from './normalize.js';
+import { parseSession } from './parse.js';
+import { decodeProjectPath } from './paths.js';
+
+const FIXTURES = join(dirname(fileURLToPath(import.meta.url)), '..', 'fixtures');
+
+describe('fixture 01 — simple agent transcript', () => {
+  it('emits a cursor session with decoded project path', async () => {
+    const rawPath = join(
+      '/Users/me/.cursor/projects/Users-me-code-fixture/agent-transcripts',
+      'aaaa-bbbb-cccc-dddd-eeeeeeeeeeee/aaaa-bbbb-cccc-dddd-eeeeeeeeeeee.jsonl',
+    );
+    const raws = await parseSession(join(FIXTURES, '01-simple.jsonl'));
+    const { session, events } = normalizeSession(raws, {
+      rawPath,
+      sessionId: 'aaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
+      formatVersion: '2026-q1',
+      fileMtimeMs: new Date('2026-05-18T12:00:05.000Z').getTime(),
+      encodedProjectDir: 'Users-me-code-fixture',
+    });
+    expect(session.harness).toBe('cursor');
+    expect(session.session_id).toBe('aaaa-bbbb-cccc-dddd-eeeeeeeeeeee');
+    expect(session.project_path).toBe('/Users/me/code/fixture');
+    expect(session.title).toMatch(/Read the README/);
+    expect(session.model).toBeNull();
+    expect(events.length).toBeGreaterThan(0);
+  });
+
+  it('splits assistant blocks and emits tool_call without upstream id', async () => {
+    const { events } = await loadSession(join(FIXTURES, '01-simple.jsonl'));
+    const toolCalls = events.filter((e) => e.event_type === 'tool_call');
+    expect(toolCalls.length).toBe(1);
+    expect(toolCalls[0]!.tool.name).toBe('Read');
+    expect(toolCalls[0]!.event_id).toMatch(/^cursor:/);
+    expect(events.some((e) => e.event_type === 'tool_result')).toBe(false);
+  });
+
+  it('strips user_query wrappers from user messages', async () => {
+    const { events } = await loadSession(join(FIXTURES, '01-simple.jsonl'));
+    const user = events.find((e) => e.role === 'user');
+    expect(user!.content).toBe('Read the README and summarize it');
+  });
+
+  it('starts a new turn per user message', async () => {
+    const { events } = await loadSession(join(FIXTURES, '01-simple.jsonl'));
+    const turnIds = new Set(events.map((e) => e.turn_id));
+    expect(turnIds.size).toBe(1);
+  });
+});
+
+describe('parseTranscriptPath', () => {
+  it('detects subagent transcripts', () => {
+    const p =
+      '/Users/me/.cursor/projects/Users-me-proj/agent-transcripts/parent-uuid/subagents/child-uuid.jsonl';
+    const info = parseTranscriptPath(p);
+    expect(info.subagent).toBe(true);
+    expect(info.parent_session_id).toBe('parent-uuid');
+    expect(info.encoded_project_dir).toBe('Users-me-proj');
+  });
+});
+
+describe('decodeProjectPath', () => {
+  it('decodes macOS-style encoded dirs', () => {
+    expect(decodeProjectPath('Users-skndsh-Desktop-projects-tracebench')).toBe(
+      '/Users/skndsh/Desktop/projects/tracebench',
+    );
+  });
+});

package/src/normalize.ts

@@ -0,0 +1,331 @@
+// Convert Cursor agent-transcript JSONL into canonical Tracebench events.
+//
+// Cursor writes supplementary logs under ~/.cursor/projects/.../agent-transcripts/.
+// Format is Anthropic-like (role + message.content blocks) but:
+//   - no per-line timestamps (synthetic timestamps from file mtime)
+//   - tool_use blocks have no id field
+//   - no tool_result lines — tool outputs are not exported separately
+//
+// Turn boundaries: each user text message starts a new turn.
+
+import type { CanonicalEvent, EventTool, EventType, Session } from '@tracebench/core';
+import type { RawCursorEvent } from './parse.js';
+import { decodeProjectPath } from './paths.js';
+
+interface NormalizeOptions {
+  rawPath: string;
+  sessionId?: string;
+  formatVersion: string;
+  /** File mtime (ms) — used for synthetic per-line timestamps. */
+  fileMtimeMs?: number;
+  encodedProjectDir?: string;
+}
+
+export interface NormalizeResult {
+  session: Session;
+  events: CanonicalEvent[];
+}
+
+function emptyTool(): EventTool {
+  return { name: null, input: null, output: null, status: null, error_message: null };
+}
+
+const emptyTokens = {
+  input: null,
+  output: null,
+  cache_read: null,
+  cache_creation: null,
+  reasoning: null,
+} as const;
+
+function toString(content: unknown): string | null {
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) {
+    const parts = content
+      .map((b) => {
+        if (typeof b === 'string') return b;
+        if (b && typeof b === 'object' && 'text' in b && typeof (b as { text: unknown }).text === 'string') {
+          return (b as { text: string }).text;
+        }
+        return '';
+      })
+      .filter((s) => s.length > 0);
+    return parts.length > 0 ? parts.join('\n') : null;
+  }
+  return null;
+}
+
+function stripUserQuery(text: string | null): string | null {
+  if (text == null) return null;
+  const stripped = text.replace(/<\/?user_query>/gi, '').trim();
+  return stripped.length > 0 ? stripped : null;
+}
+
+function deriveTitle(content: unknown): string | null {
+  const s = stripUserQuery(toString(content));
+  if (!s) return null;
+  const single = s.replace(/\s+/g, ' ').trim();
+  if (!single) return null;
+  return single.length > 120 ? single.slice(0, 117) + '...' : single;
+}
+
+export function parseTranscriptPath(rawPath: string): {
+  encoded_project_dir: string | null;
+  subagent: boolean;
+  parent_session_id: string | null;
+} {
+  const dirMatch = rawPath.match(/\/projects\/([^/]+)\/agent-transcripts\//);
+  const encoded = dirMatch ? dirMatch[1]! : null;
+  const subMatch = /\/agent-transcripts\/([^/]+)\/subagents\/([^/]+)\.jsonl$/i.exec(rawPath);
+  if (subMatch) {
+    return {
+      encoded_project_dir: encoded,
+      subagent: true,
+      parent_session_id: subMatch[1]!,
+    };
+  }
+  return { encoded_project_dir: encoded, subagent: false, parent_session_id: null };
+}
+
+function syntheticTimestamps(lineCount: number, endMs: number): string[] {
+  if (lineCount === 0) return [];
+  const span = Math.max(lineCount - 1, 0) * 1000;
+  const startMs = endMs - span;
+  return Array.from({ length: lineCount }, (_, i) =>
+    new Date(startMs + i * 1000).toISOString(),
+  );
+}
+
+export function normalizeSession(
+  raws: RawCursorEvent[],
+  opts: NormalizeOptions,
+): NormalizeResult {
+  const pathInfo = parseTranscriptPath(opts.rawPath);
+  const encodedDir =
+    opts.encodedProjectDir ?? pathInfo.encoded_project_dir ?? 'unknown';
+  const projectPath = decodeProjectPath(encodedDir);
+
+  let resolvedSessionId = opts.sessionId ?? null;
+  if (!resolvedSessionId) {
+    resolvedSessionId =
+      opts.rawPath.split('/').pop()?.replace(/\.jsonl$/, '') ?? 'unknown';
+  }
+
+  const endMs = opts.fileMtimeMs ?? Date.now();
+  const timestamps = syntheticTimestamps(raws.length, endMs);
+  const firstTs = timestamps[0] ?? new Date(endMs).toISOString();
+  const lastTs = timestamps[timestamps.length - 1] ?? firstTs;
+
+  let firstUser: RawCursorEvent | undefined;
+  for (const r of raws) {
+    if (r.role === 'user' && !firstUser) firstUser = r;
+  }
+
+  const titleSource = firstUser
+    ? ((firstUser.message as { content?: unknown } | undefined)?.content ?? null)
+    : null;
+  const title = deriveTitle(titleSource);
+
+  const source = {
+    harness: 'cursor' as const,
+    format_version: opts.formatVersion,
+    raw_path: opts.rawPath,
+  };
+
+  const sessionMeta: Record<string, unknown> = {
+    encoded_project_dir: encodedDir,
+  };
+  if (pathInfo.subagent) {
+    sessionMeta.subagent = true;
+    if (pathInfo.parent_session_id) sessionMeta.parent_session_id = pathInfo.parent_session_id;
+  }
+
+  const events: CanonicalEvent[] = [];
+  let turnIndex = 0;
+  let currentTurnId = `${resolvedSessionId}::t0`;
+
+  function newTurn(): string {
+    turnIndex += 1;
+    currentTurnId = `${resolvedSessionId}::t${turnIndex}`;
+    return currentTurnId;
+  }
+
+  function baseMeta(extra: Record<string, unknown> = {}): Record<string, unknown> {
+    return { ...sessionMeta, ...extra };
+  }
+
+  for (let lineIndex = 0; lineIndex < raws.length; lineIndex++) {
+    const r = raws[lineIndex]!;
+    const ts = timestamps[lineIndex] ?? lastTs;
+    const role = typeof r.role === 'string' ? r.role : 'unknown';
+
+    if (role === 'user') {
+      newTurn();
+      const content = (r.message as { content?: unknown } | undefined)?.content;
+      events.push({
+        event_id: `cursor:${resolvedSessionId}:u:${lineIndex}`,
+        session_id: resolvedSessionId,
+        turn_id: currentTurnId,
+        parent_event_id: null,
+        timestamp: ts,
+        source,
+        role: 'user',
+        event_type: 'message',
+        model: null,
+        tokens: { ...emptyTokens },
+        cost_usd: null,
+        cost_method: null,
+        duration_ms: null,
+        content: stripUserQuery(toString(content)),
+        tool: emptyTool(),
+        metadata: baseMeta(),
+        raw: r,
+      });
+      continue;
+    }
+
+    if (role === 'assistant') {
+      const msg = (r.message as { content?: unknown } | undefined) ?? {};
+      const blocks = Array.isArray(msg.content) ? msg.content : [];
+
+      if (blocks.length === 0) {
+        events.push({
+          event_id: `cursor:${resolvedSessionId}:a:${lineIndex}:0`,
+          session_id: resolvedSessionId,
+          turn_id: currentTurnId,
+          parent_event_id: null,
+          timestamp: ts,
+          source,
+          role: 'assistant',
+          event_type: 'message',
+          model: null,
+          tokens: { ...emptyTokens },
+          cost_usd: null,
+          cost_method: null,
+          duration_ms: null,
+          content: null,
+          tool: emptyTool(),
+          metadata: baseMeta({ empty: true }),
+          raw: r,
+        });
+        continue;
+      }
+
+      for (let bi = 0; bi < blocks.length; bi++) {
+        const block = blocks[bi] as Record<string, unknown>;
+        const blockType = typeof block.type === 'string' ? block.type : '';
+        const eventId = `cursor:${resolvedSessionId}:${lineIndex}:${bi}`;
+
+        let evtType: EventType = 'message';
+        let toolInfo = emptyTool();
+        let contentField: CanonicalEvent['content'] = null;
+
+        if (blockType === 'text') {
+          evtType = 'message';
+          contentField = typeof block.text === 'string' ? block.text : null;
+        } else if (blockType === 'tool_use') {
+          evtType = 'tool_call';
+          toolInfo = {
+            name: typeof block.name === 'string' ? block.name : null,
+            input: (block.input as Record<string, unknown> | undefined) ?? null,
+            output: null,
+            status: null,
+            error_message: null,
+          };
+        } else if (blockType === 'thinking') {
+          evtType = 'thinking';
+          contentField =
+            typeof block.thinking === 'string'
+              ? block.thinking
+              : typeof block.text === 'string'
+                ? block.text
+                : null;
+        } else {
+          evtType = 'meta';
+          contentField = block as unknown as CanonicalEvent['content'];
+        }
+
+        events.push({
+          event_id: eventId,
+          session_id: resolvedSessionId,
+          turn_id: currentTurnId,
+          parent_event_id: null,
+          timestamp: ts,
+          source,
+          role: 'assistant',
+          event_type: evtType,
+          model: null,
+          tokens: { ...emptyTokens },
+          cost_usd: null,
+          cost_method: null,
+          duration_ms: null,
+          content: contentField,
+          tool: toolInfo,
+          metadata: baseMeta(blockType && blockType !== 'text' ? { block_type: blockType } : {}),
+          raw: bi === 0 ? r : { _ref_line: lineIndex },
+        });
+      }
+      continue;
+    }
+
+    events.push({
+      event_id: `cursor:${resolvedSessionId}:meta:${lineIndex}`,
+      session_id: resolvedSessionId,
+      turn_id: currentTurnId,
+      parent_event_id: null,
+      timestamp: ts,
+      source,
+      role: 'system',
+      event_type: 'meta',
+      model: null,
+      tokens: { ...emptyTokens },
+      cost_usd: null,
+      cost_method: null,
+      duration_ms: null,
+      content: null,
+      tool: emptyTool(),
+      metadata: baseMeta({ kind: role }),
+      raw: r,
+    });
+  }
+
+  const session: Session = {
+    session_id: resolvedSessionId,
+    harness: 'cursor',
+    project_path: projectPath,
+    title,
+    started_at: firstTs,
+    ended_at: lastTs,
+    model: null,
+    raw_path: opts.rawPath,
+    format_version: opts.formatVersion,
+    mtime_ms: 0,
+  };
+
+  return { session, events };
+}
+
+import { parseSession } from './parse.js';
+import { promises as fs } from 'node:fs';
+
+export async function loadSession(
+  filePath: string,
+  opts: { formatVersion?: string; encodedProjectDir?: string } = {},
+): Promise<NormalizeResult> {
+  const raws = await parseSession(filePath);
+  let fileMtimeMs: number | undefined;
+  try {
+    const st = await fs.stat(filePath);
+    fileMtimeMs = st.mtimeMs;
+  } catch {
+    // ignore
+  }
+  const sessionId = filePath.split('/').pop()?.replace(/\.jsonl$/, '');
+  return normalizeSession(raws, {
+    rawPath: filePath,
+    sessionId,
+    formatVersion: opts.formatVersion ?? '2026-q1',
+    fileMtimeMs,
+    encodedProjectDir: opts.encodedProjectDir,
+  });
+}

package/src/parse.ts

@@ -0,0 +1,30 @@
+// Stream a Cursor agent-transcript JSONL file line by line.
+
+import { createReadStream } from 'node:fs';
+import { createInterface } from 'node:readline';
+
+export type RawCursorEvent = Record<string, unknown> & {
+  role?: string;
+  message?: unknown;
+};
+
+export async function* streamSession(
+  filePath: string,
+): AsyncIterable<RawCursorEvent> {
+  const stream = createReadStream(filePath, { encoding: 'utf8' });
+  const rl = createInterface({ input: stream, crlfDelay: Infinity });
+  for await (const line of rl) {
+    if (!line.trim()) continue;
+    try {
+      yield JSON.parse(line) as RawCursorEvent;
+    } catch {
+      continue;
+    }
+  }
+}
+
+export async function parseSession(filePath: string): Promise<RawCursorEvent[]> {
+  const out: RawCursorEvent[] = [];
+  for await (const ev of streamSession(filePath)) out.push(ev);
+  return out;
+}

package/src/paths.ts

@@ -0,0 +1,46 @@
+// Cursor on-disk path helpers (JSONL roots + future Composer SQLite locations).
+
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export function defaultCursorProjectsRoot(): string {
+  return join(homedir(), '.cursor', 'projects');
+}
+
+/** VS Code–style Cursor `User/` data directory (global + workspace DBs). */
+export function defaultCursorUserDataDir(): string {
+  const home = homedir();
+  switch (process.platform) {
+    case 'darwin':
+      return join(home, 'Library', 'Application Support', 'Cursor', 'User');
+    case 'win32': {
+      const appData = process.env.APPDATA ?? join(home, 'AppData', 'Roaming');
+      return join(appData, 'Cursor', 'User');
+    }
+    default:
+      return join(home, '.config', 'Cursor', 'User');
+  }
+}
+
+/** Global Composer DB — Phase 2 reads this (not used by JSONL adapter yet). */
+export function defaultCursorGlobalDbPath(): string {
+  return join(defaultCursorUserDataDir(), 'globalStorage', 'state.vscdb');
+}
+
+/**
+ * Decode sanitized project dir name back to an absolute path (best-effort).
+ * Cursor encodes `/Users/me/proj` → `Users-me-proj` (leading slash stripped).
+ */
+export function decodeProjectPath(encoded: string): string {
+  if (encoded.startsWith('Users-')) {
+    return '/Users/' + encoded.slice('Users-'.length).replace(/-/g, '/');
+  }
+  if (encoded.startsWith('home-')) {
+    return '/' + encoded.replace(/-/g, '/');
+  }
+  if (/^[A-Za-z]-/.test(encoded)) {
+    const drive = encoded[0]!.toUpperCase();
+    return drive + ':\\' + encoded.slice(2).replace(/-/g, '\\');
+  }
+  return encoded;
+}

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "types": ["node"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["dist", "node_modules", "**/*.test.ts"]
+}

package/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    include: ['src/**/*.test.ts'],
+  },
+});