Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

17.5 KB
Raw Blame
import { externalEvidenceActive, externalReadFailed } from '../evidence.js'
/**
 * Cursor (`cursor-agent`, also `agent`): a chat is `<configDir>/chats/<md5(folder)>/<id>/`, holding its
 * `store.db` (SQLite, WAL) and `meta.json`, which says its title, when it last moved, the folder it
 * ran in, and whether it is a sub-agent's or still empty. What was said is a separate transcript
 * under the data folder: `<dataDir>/projects/<slug(folder)>/agent-transcripts/<id>/<id>.jsonl`.
 *
 * `--resume` looks for a chat only in the bucket of the folder it runs in, so a chat is offered with
 * a folder only when that folder's md5 is its bucket's name. Every chat in a bucket shares its folder,
 * so one chat that names it names it for all. The slug is lossy (`/a/b-c` and `/a/b/c` are both
 * `a-b-c`) and is never read as a folder; it only guides a walk whose every answer the md5 checks.
 *
 * No `store.db` means no chat Cursor can resume (the IDE's transcripts, a worker's runs elsewhere).
 * A `--print` run cannot be told from a person's chat: both are listed.
 *
 * A running Cursor holds its chat's `store.db` open for the life of the chat, so `lsof` names the
 * owner; `--resume <id>` in its arguments is the fallback. A chat inside Cursor's own tmux server
 * (`tmux -L cursor-agent`, its "persistent sessions") is stopped with `agent persist stop`, never by
 * a signal from here.
 */

import { createHash } from 'node:crypto'
import type { Dirent } from 'node:fs'
import { readFile, realpath, stat } from 'node:fs/promises'
import { basename, dirname, join, resolve } from 'node:path'
import { pathToFileURL } from 'node:url'

import { agentCommandOwnershipSnapshot } from '../../engineBin.js'
import { builtinSqlite } from '../../sqliteBuiltin.js'
import { argvTokens, engineProcessMatch, resumeSessionId } from '../../processTable.js'
import { absoluteFolder, entries, fileStamp, parseLine, readJson, readTail, record, text, UUID } from './support.js'
import type { ExternalProvider, ExternalSession, OwnerClaim, ProcessView, RunningProcess, ScanContext } from './types.js'

/** The read-only SQLite a chat store is read with; `node:sqlite`'s `DatabaseSync` in production. */
export interface CursorDatabase {
  new (path: string | URL, options: { readOnly: boolean }): { prepare(sql: string): { get(): unknown }; close(): void }
}

export interface CursorOptions {
  configDir: string
  dataDir: string
  /** How a chat with no `meta.json` has its store read; null when this Node has no SQLite. Tests set it. */
  database?: CursorDatabase | null
  /** How the walk for a lost folder lists a folder; the file system's own (`entries`) unless a test shows it
   *  less: the walk starts at `/`, and a test's folders sit beside every other in a shared temp folder. */
  listFolder?: (dir: string) => Promise<Dirent[]>
}

/** A chat's own account of itself, from `meta.json` or, when that is missing, its store. */
export interface CursorMeta {
  title: string
  /** When the chat last moved (`updatedAtMs`); null when it does not say. */
  updatedAt: number | null
  hasConversation: boolean
  isSubagent: boolean
  cwd: string | null
}

export type CursorSkip = 'no-store' | 'unreadable' | 'subagent' | 'empty'

const BUCKET = /^[0-9a-f]{32}$/
/** Cursor's name for a chat nobody named. */
const DEFAULT_TITLE = 'New Agent'
const META_MAX_BYTES = 64 * 1024
const TAIL_BYTES = [256 * 1024, 4 * 1024 * 1024]
/** How many folders a walk for a lost folder may list before it gives up. */
const WALK_READS = 256

/** Cursor's project name for a folder: every run of other characters becomes one `-`, trimmed. */
export function cursorSlug(folder: string): string {
  return folder.replace(/[^a-zA-Z0-9]/g, '-').replace(/-+/g, '-').replace(/^-+|-+$/g, '')
}

/** A folder's bucket name: the md5 of its resolved path. */
export function cursorBucket(folder: string): string {
  return createHash('md5').update(resolve(folder)).digest('hex')
}

function cursorTitle(value: unknown): string {
  const title = text(value).trim()
  return title === DEFAULT_TITLE ? '' : title
}

/** `meta.json` as Cursor itself reads it: without a numeric `createdAtMs` it is not one. */
export function parseCursorMeta(value: unknown): CursorMeta | null {
  const row = record(value)
  if (!row || typeof row.createdAtMs !== 'number' || !Number.isFinite(row.createdAtMs)) return null
  const updated = row.updatedAtMs
  return {
    title: cursorTitle(row.title),
    updatedAt: typeof updated === 'number' && Number.isFinite(updated) && updated > 0 ? Math.floor(updated) : null,
    hasConversation: row.hasConversation === true,
    isSubagent: row.isSubagent === true,
    cwd: absoluteFolder(row.cwd),
  }
}

/**
 * A chat store's own metadata (`meta` row `0`, hex-encoded JSON), for a chat whose `meta.json` is
 * missing. Opening a WAL database creates its `-wal` and `-shm` files when they are not there, so a
 * store without them (its Cursor closed it cleanly, and the main file holds everything) is opened
 * immutable: nothing is written beside it. A store that cannot be opened throws; the next scan tries
 * again.
 */
export async function readStoreMeta(storePath: string, Database: CursorDatabase | null): Promise<CursorMeta | null> {
  if (!Database) return null
  const [wal, shm] = await Promise.all([fileStamp(`${storePath}-wal`), fileStamp(`${storePath}-shm`)])
  const url = pathToFileURL(storePath)
  url.search = 'immutable=1'
  const db = new Database(wal && shm ? storePath : url, { readOnly: true })
  let value: unknown
  try {
    value = record(db.prepare("SELECT value FROM meta WHERE key = '0' LIMIT 1").get())?.value
  } finally {
    db.close()
  }
  const hex = text(value)
  if (!hex || hex.length > META_MAX_BYTES * 2 || !/^(?:[0-9a-f]{2})+$/i.test(hex)) return null
  const meta = record(parseLine(Buffer.from(hex, 'hex').toString('utf8')))
  if (!meta || (text(meta.agentId) && meta.agentId !== basename(dirname(storePath)))) return null
  return {
    title: cursorTitle(meta.name),
    updatedAt: null,
    hasConversation: text(meta.latestRootBlobId).length > 0,
    isSubagent: meta.subagentInfo !== undefined && meta.subagentInfo !== null,
    cwd: null,
  }
}

/** The first answer [pick] gives, reading lines back from the end of [path]. */
async function fromEnd<T>(path: string, pick: (line: string) => T | null): Promise<T | null> {
  const size = (await stat(path).catch(error => { externalReadFailed(error, 'record'); return null }))?.size ?? 0
  for (const bytes of TAIL_BYTES) {
    const lines = (await readTail(path, bytes)).split('\n')
    // A window that starts mid-file starts mid-line.
    for (let i = lines.length - 1; i >= (size > bytes ? 1 : 0); i--) {
      const found = pick(lines[i])
      if (found !== null) return found
    }
    if (size <= bytes) break
  }
  return null
}

/**
 * Whether a chat's last turn is still running: a prompt after the last `turn_ended`. Cursor writes the
 * transcript at each checkpoint of the chat, so it trails the chat: a turn that just ended can read
 * as running (the safe way: Harness asks before stopping it), and a prompt just sent can read as
 * idle until its first checkpoint. Null when the end of the transcript says neither.
 */
export function cursorTurnOpen(path: string): Promise<boolean | null> {
  return fromEnd(path, (line) => {
    const row = record(parseLine(line))
    if (row?.type === 'turn_ended') return false
    return row?.role === 'user' ? true : null
  })
}

/** A transcript, and the project (the slug of a folder) it is filed under. */
interface Transcript { path: string; project: string }

/** Transcripts by chat id, for chats whose own folder's project holds none: every project, listed once. */
async function transcriptIndex(dataDir: string): Promise<Map<string, Transcript>> {
  const projects = join(dataDir, 'projects')
  const found = new Map<string, Transcript>()
  for (const project of await entries(projects)) {
    if (!project.isDirectory()) continue
    const dir = join(projects, project.name, 'agent-transcripts')
    for (const entry of await entries(dir)) {
      const flat = entry.name.replace(/\.jsonl$/, '')
      if (entry.isDirectory() && UUID.test(entry.name)) {
        found.set(entry.name, { path: join(dir, entry.name, `${entry.name}.jsonl`), project: project.name })
      } else if (entry.isFile() && flat !== entry.name && UUID.test(flat) && !found.has(flat)) {
        // The layout older builds wrote: `agent-transcripts/<id>.jsonl`.
        found.set(flat, { path: join(dir, entry.name), project: project.name })
      }
    }
  }
  return found
}

/** A chat's transcript: where its folder puts it, else wherever a project holds one by its id. */
async function transcriptOf(
  dataDir: string, sessionId: string, cwd: string | null, index: () => Promise<Map<string, Transcript>>,
): Promise<Transcript | null> {
  if (cwd) {
    const project = cursorSlug(cwd)
    const path = join(dataDir, 'projects', project, 'agent-transcripts', sessionId, `${sessionId}.jsonl`)
    if (await fileStamp(path)) return { path, project }
  }
  const elsewhere = (await index()).get(sessionId)
  return elsewhere && await fileStamp(elsewhere.path) ? elsewhere : null
}

/**
 * The folder whose bucket is [bucket] and whose slug is [slug], walked down to from `/` through real
 * folders whose slugs lead to it. The md5 decides: a slug alone never names a folder.
 */
async function walkToFolder(slug: string, bucket: string, list: (dir: string) => Promise<Dirent[]> = entries): Promise<string | null> {
  let reads = WALK_READS
  const walk = async (dir: string): Promise<string | null> => {
    const own = cursorSlug(dir)
    if (own === slug && cursorBucket(dir) === bucket) return dir
    if (own && own !== slug && !slug.startsWith(`${own}-`)) return null
    if (reads-- <= 0) return null
    for (const entry of await list(dir)) {
      if (!entry.isDirectory()) continue
      const found = await walk(join(dir, entry.name))
      if (found) return found
    }
    return null
  }
  return walk('/')
}

interface Chat {
  sessionId: string
  meta: CursorMeta
  /** When it last moved: `updatedAtMs`, else the store's last write. */
  movedAt: number
}

type ChatRead = { kind: 'chat'; chat: Chat } | { kind: 'skip'; reason: CursorSkip }

/** One chat folder, classified. Its metadata is read again only when one of its files changed. */
export async function readChat(ctx: ScanContext, chatDir: string, Database: () => CursorDatabase | null): Promise<ChatRead> {
  const store = join(chatDir, 'store.db')
  const [db, wal, meta] = await Promise.all([fileStamp(store), fileStamp(`${store}-wal`), fileStamp(join(chatDir, 'meta.json'))])
  if (!db) return { kind: 'skip', reason: 'no-store' }
  let read: CursorMeta | null
  try {
    read = await ctx.memo(`cursor:${chatDir}`, `${meta?.stamp ?? '-'}|${db.stamp}|${wal?.stamp ?? '-'}`, async () => {
      // A `meta.json` Cursor is still writing is not JSON yet, and throws: nothing is remembered, and
      // the next scan reads it again. One that is not a sidecar is read past, as Cursor reads past it.
      const source = await readFile(join(chatDir, 'meta.json'), 'utf8').catch(error => { externalReadFailed(error, 'record'); return null })
      return (source === null ? null : parseCursorMeta(JSON.parse(source))) ?? readStoreMeta(store, Database())
    })
  } catch (error) {
    externalReadFailed(error, 'conversation metadata')
    // Half-written, or a store that could not be opened: read again next scan.
    read = null
  }
  if (!read) { externalReadFailed(new Error('unreadable'), 'conversation metadata'); return { kind: 'skip', reason: 'unreadable' } }
  if (read.isSubagent) return { kind: 'skip', reason: 'subagent' }
  if (!read.hasConversation) return { kind: 'skip', reason: 'empty' }
  return { kind: 'chat', chat: { sessionId: basename(chatDir), meta: read, movedAt: read.updatedAt ?? Math.max(db.mtime, wal?.mtime ?? 0) } }
}

/** Whether [row] runs inside Cursor's own tmux server (`tmux -L cursor-agent`), a few parents up. */
function persistent(row: RunningProcess, byPid: ReadonlyMap<number, RunningProcess>): boolean {
  let parent = byPid.get(row.ppid)
  for (let depth = 0; parent && depth < 4; depth++) {
    const tokens = argvTokens(parent.args)
    const tmux = basename(parent.executable) === 'tmux' || basename(tokens[0] ?? '') === 'tmux'
    if (tmux && tokens.some((token, i) => /^-Lcursor/.test(token) || (token === '-L' && /^cursor/.test(tokens[i + 1] ?? '')))) return true
    parent = byPid.get(parent.ppid)
  }
  return false
}

export function cursorProvider(options: CursorOptions): ExternalProvider {
  const chatsRoot = join(options.configDir, 'chats')
  let database: CursorDatabase | null | undefined = options.database
  const Database = (): CursorDatabase | null => (database === undefined ? (database = builtinSqlite() as unknown as CursorDatabase | null) : database)

  /** The store of chat [sessionId], in whichever bucket holds it. */
  async function storeOf(sessionId: string): Promise<string | null> {
    for (const bucket of await entries(chatsRoot)) {
      const path = join(chatsRoot, bucket.name, sessionId, 'store.db')
      if (bucket.isDirectory() && BUCKET.test(bucket.name) && await fileStamp(path)) return path
    }
    return null
  }

  return {
    engine: 'cursor',
    async scan(ctx: ScanContext): Promise<ExternalSession[]> {
      let listed: Promise<Map<string, Transcript>> | null = null
      const index = () => (listed ??= transcriptIndex(options.dataDir))
      const found: ExternalSession[] = []
      for (const bucket of await entries(chatsRoot)) {
        if (!bucket.isDirectory() || !BUCKET.test(bucket.name)) continue
        const bucketDir = join(chatsRoot, bucket.name)
        const chats: Chat[] = []
        for (const entry of await entries(bucketDir)) {
          if (!entry.isDirectory() || !UUID.test(entry.name)) continue
          const read = await readChat(ctx, join(bucketDir, entry.name), Database)
          await ctx.pace()
          if (read.kind === 'chat') chats.push(read.chat)
        }
        if (!chats.length) continue
        // A chat that names a folder whose md5 is the bucket names it for every chat there.
        const named = chats.map((chat) => chat.meta.cwd).find((cwd) => cwd && cursorBucket(cwd) === bucket.name)
        const cwd = named ? resolve(named) : await ctx.memo(`cursor:folder:${bucketDir}`, chats.map((chat) => chat.sessionId).sort().join(','), async () => {
          // None does (chats older than their `cwd`): the project a transcript is filed under guides a walk.
          const tried = new Set<string>()
          for (const chat of chats) {
            const project = (await transcriptOf(options.dataDir, chat.sessionId, null, index))?.project
            if (!project || tried.has(project)) continue
            tried.add(project)
            const folder = await walkToFolder(project, bucket.name, options.listFolder)
            if (folder) return folder
          }
          return null
        })
        if (!cwd || ctx.excluded(cwd)) continue
        for (const chat of chats) {
          found.push({
            sessionId: chat.sessionId, engine: 'cursor', cwd, origin: 'terminal', title: chat.meta.title, mtime: chat.movedAt,
            transcriptPath: (await transcriptOf(options.dataDir, chat.sessionId, cwd, index))?.path ?? null,
          })
        }
      }
      return found
    },
    async owners(view: ProcessView): Promise<OwnerClaim[]> {
      const rows = await view.list()
      const ownership = agentCommandOwnershipSnapshot()
      const cursor = rows.filter((row) => engineProcessMatch(row, 'cursor', ownership).score > 0 && view.alive(row.pid))
      if (!cursor.length) return []
      const byPid = new Map(rows.map((row) => [row.pid, row]))
      const roots = new Set([chatsRoot, join(await realpath(options.configDir).catch(error => { externalReadFailed(error, 'folder'); return options.configDir }), 'chats')])
      const files = await view.openFiles(cursor.map((row) => row.pid))
      const claims: OwnerClaim[] = []
      for (const row of cursor) {
        const app = persistent(row, byPid) ? { app: true } : {}
        const held = new Set<string>()
        for (const path of files.get(row.pid) ?? []) {
          const store = path.replace(/-(?:wal|shm)$/, '')
          const chatDir = dirname(store)
          const sessionId = basename(chatDir)
          if (basename(store) !== 'store.db' || !UUID.test(sessionId) || !BUCKET.test(basename(dirname(chatDir)))) continue
          const key = externalEvidenceActive() ? store : sessionId
          if (!roots.has(dirname(dirname(chatDir))) || held.has(key)) continue
          held.add(key)
          claims.push({ sessionId, pid: row.pid, record: store, ...app })
        }
        if (held.size) continue
        externalReadFailed(new Error('no current open store for a live process'), 'current owner')
        // No chat store open (yet, or `lsof` could not say): the chat its arguments name.
        const resumed = resumeSessionId('cursor', row.args)
        // A guess: an in-app `/resume` leaves the arguments naming the first chat. Never stopped on it.
        if (resumed && UUID.test(resumed)) claims.push({ sessionId: resumed, pid: row.pid, record: await storeOf(resumed) ?? '', fromArgs: true, ...app })
      }
      return claims
    },
    async busy(owner): Promise<boolean | null> {
      if (!owner.record) return null
      const chatDir = dirname(owner.record)
      const meta = parseCursorMeta(await readJson(join(chatDir, 'meta.json')))
      const cwd = meta?.cwd && cursorBucket(meta.cwd) === basename(dirname(chatDir)) ? meta.cwd : null
      const transcript = await transcriptOf(options.dataDir, basename(chatDir), cwd, () => transcriptIndex(options.dataDir))
      return transcript ? cursorTurnOpen(transcript.path) : null
    },
  }
}