failproofai 0.0.9 → 0.0.10-beta.1

package/lib/copilot-sessions.ts

@@ -0,0 +1,395 @@
+/**
+ * GitHub Copilot CLI session transcript discovery + JSONL parser.
+ *
+ * Copilot stores per-session state at:
+ *   ~/.copilot/session-state/<sessionId>/
+ *     workspace.yaml           — session metadata (id, cwd, git_root, branch, …)
+ *     events.jsonl             — event log (only created after first interaction)
+ *     session.db               — per-session SQLite (cross-session index lives at ~/.copilot/session-store.db)
+ *     checkpoints/index.md     — checkpoint history
+ *     files/, research/        — workspace artifacts
+ *
+ * (configurable via COPILOT_HOME). Each `events.jsonl` line is a record with
+ * shape `{ type, data, id, timestamp, parentId }` where `type` is a dotted
+ * path. Verified record types as of Copilot CLI 1.0.39:
+ *   • session.start         — data.sessionId, data.context.{cwd, gitRoot, branch, repository, headCommit}
+ *   • session.model_change  — data.newModel
+ *   • session.shutdown      — data.shutdownType, data.codeChanges, …
+ *   • system.message        — data.role, data.content
+ *   • user.message          — data.content, data.transformedContent
+ *   • assistant.turn_start  — data.turnId, data.interactionId
+ *   • assistant.message     — data.messageId, data.content, data.toolRequests
+ *   • assistant.turn_end    — data.turnId
+ *   • tool.execution_start  — data.toolCallId, data.toolName, data.arguments
+ *   • tool.execution_complete — data.toolCallId, data.success, data.result.{content, detailedContent}
+ *
+ * Unknown record types are preserved as generic system entries so nothing is
+ * silently dropped.
+ *
+ * Refs:
+ *   https://docs.github.com/en/copilot/concepts/agents/copilot-cli/chronicle
+ *   https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-config-dir-reference
+ */
+import { readFileSync, readdirSync, existsSync, statSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join, resolve, sep } from "node:path";
+import { homedir } from "node:os";
+import { runtimeCache } from "./runtime-cache";
+import {
+  baseEntry,
+  formatTimestamp,
+  type LogEntry,
+  type UserEntry,
+  type AssistantEntry,
+  type GenericEntry,
+  type QueueOperationEntry,
+  type ContentBlock,
+  type ToolUseBlock,
+  type LogSource,
+} from "./log-entries";
+import { formatDuration } from "./format-duration";
+
+// ── Paths ──
+
+/** Root directory for Copilot CLI session state, honoring COPILOT_HOME. */
+export function getCopilotHome(): string {
+  return process.env.COPILOT_HOME || join(homedir(), ".copilot");
+}
+
+export function getCopilotSessionStateRoot(): string {
+  return join(getCopilotHome(), "session-state");
+}
+
+/** Session-state dir for a given sessionId. Returns null if `sessionId` is
+ *  empty or contains path-traversal segments that would escape the
+ *  session-state root. */
+export function getCopilotSessionDir(sessionId: string): string | null {
+  if (!sessionId) return null;
+  const root = resolve(getCopilotSessionStateRoot());
+  const candidate = resolve(root, sessionId);
+  // Containment check: the resolved path must be a child of `root`.
+  // (Equality means `sessionId` resolved to root itself — also rejected.)
+  if (candidate === root || !candidate.startsWith(`${root}${sep}`)) return null;
+  return candidate;
+}
+
+/** Resolve a single file under a session directory, applying the same
+ *  containment check. Returns null if the sessionId is invalid. */
+function resolveSessionFile(sessionId: string, filename: string): string | null {
+  const dir = getCopilotSessionDir(sessionId);
+  if (!dir) return null;
+  return join(dir, filename);
+}
+
+// ── Transcript discovery ──
+
+/**
+ * Locate a Copilot CLI events.jsonl by sessionId. Copilot lays sessions out
+ * directly under `session-state/<sessionId>/events.jsonl` (only created after
+ * the first user interaction), so the lookup is a single existence check.
+ * Path-traversal sessionIds (`../foo`) are rejected.
+ *
+ * Synchronous so the hook hot path can call it without awaits.
+ */
+export function findCopilotTranscript(sessionId: string): string | null {
+  const candidate = resolveSessionFile(sessionId, "events.jsonl");
+  if (!candidate) return null;
+  return existsSync(candidate) ? candidate : null;
+}
+
+/** Locate the workspace.yaml for a session (always present, even pre-interaction). */
+export function findCopilotWorkspace(sessionId: string): string | null {
+  const candidate = resolveSessionFile(sessionId, "workspace.yaml");
+  if (!candidate) return null;
+  return existsSync(candidate) ? candidate : null;
+}
+
+/**
+ * Extract a single key from the YAML at `path` using a permissive regex
+ * (avoids adding a YAML parser dep for the handful of flat scalar fields
+ * Copilot writes). Returns the trimmed string value or undefined.
+ */
+function readYamlScalar(path: string, key: string): string | undefined {
+  try {
+    const text = readFileSync(path, "utf-8");
+    const re = new RegExp(`^${key}\\s*:\\s*(.+?)\\s*$`, "m");
+    const m = text.match(re);
+    if (!m) return undefined;
+    // Strip surrounding quotes if any.
+    return m[1].replace(/^['"]|['"]$/g, "");
+  } catch {
+    return undefined;
+  }
+}
+
+/** Read the cwd recorded in workspace.yaml for a session. */
+export function readCopilotWorkspaceCwd(sessionId: string): string | undefined {
+  const path = findCopilotWorkspace(sessionId);
+  if (!path) return undefined;
+  return readYamlScalar(path, "cwd");
+}
+
+// ── Parser ──
+
+interface CopilotRecord {
+  type?: string;
+  data?: Record<string, unknown>;
+  id?: string;
+  timestamp?: string;
+  parentId?: string | null;
+}
+
+interface CopilotParseResult {
+  entries: LogEntry[];
+  rawLines: Record<string, unknown>[];
+  /** Working directory pulled from the first session.start record. */
+  cwd?: string;
+}
+
+interface CopilotToolResult {
+  content?: string;
+  detailedContent?: string;
+}
+
+interface CopilotToolTelemetry {
+  metrics?: { commandTimeMs?: number; durationMs?: number };
+  properties?: Record<string, unknown>;
+}
+
+/**
+ * Parse a Copilot CLI events.jsonl transcript into `LogEntry[]` plus the raw
+ * lines. Yields to the event loop every 200 lines so big transcripts don't
+ * block the request.
+ */
+export async function parseCopilotLog(
+  fileContent: string,
+  source: LogSource = "session",
+): Promise<CopilotParseResult> {
+  const lines = fileContent.split("\n").filter((line) => line.trim() !== "");
+  const entries: LogEntry[] = [];
+  const rawLines: Record<string, unknown>[] = [];
+  // toolCallId → tool_use block, so we can attach tool.execution_complete back.
+  const toolUseById = new Map<string, ToolUseBlock>();
+  const toolUseStartMs = new Map<string, number>();
+  let cwd: string | undefined;
+  let seenSessionStart = false;
+
+  for (let i = 0; i < lines.length; i++) {
+    if (i > 0 && i % 200 === 0) await new Promise<void>((r) => setImmediate(r));
+
+    const line = lines[i];
+    let raw: CopilotRecord;
+    try {
+      raw = JSON.parse(line) as CopilotRecord;
+    } catch {
+      continue;
+    }
+
+    const rawCopy = { ...(raw as Record<string, unknown>), _source: source };
+    rawLines.push(rawCopy);
+
+    const timestampStr = raw.timestamp;
+    if (!timestampStr) continue;
+    const date = new Date(timestampStr);
+    if (Number.isNaN(date.getTime())) continue;
+    const timestamp = date.toISOString();
+
+    const recType = raw.type;
+    const data = raw.data ?? {};
+
+    if (recType === "session.start") {
+      const ctx = data.context as { cwd?: unknown } | undefined;
+      const c = ctx?.cwd;
+      if (typeof c === "string" && !cwd) cwd = c;
+      const label: QueueOperationEntry["label"] = seenSessionStart ? "Session Resumed" : "Session Started";
+      seenSessionStart = true;
+      entries.push({
+        type: "queue-operation",
+        ...baseEntry(rawCopy, timestamp, date, source),
+        label,
+      } satisfies QueueOperationEntry);
+      continue;
+    }
+
+    if (recType === "user.message") {
+      const text = (data.content as string) ?? "";
+      if (!text) continue;
+      entries.push({
+        type: "user",
+        ...baseEntry(rawCopy, timestamp, date, source),
+        message: { role: "user", content: text },
+      } satisfies UserEntry);
+      continue;
+    }
+
+    if (recType === "system.message") {
+      // System prompts are noisy; render as a generic system entry so they're
+      // visible in the raw view but don't dominate the structured timeline.
+      entries.push({
+        type: "system",
+        ...baseEntry(rawCopy, timestamp, date, source),
+        raw: rawCopy,
+      } satisfies GenericEntry);
+      continue;
+    }
+
+    if (recType === "assistant.message") {
+      const text = (data.content as string) ?? "";
+      if (!text) {
+        entries.push({
+          type: "system",
+          ...baseEntry(rawCopy, timestamp, date, source),
+          raw: rawCopy,
+        } satisfies GenericEntry);
+        continue;
+      }
+      const blocks: ContentBlock[] = [{ type: "text", text }];
+      entries.push({
+        type: "assistant",
+        ...baseEntry(rawCopy, timestamp, date, source),
+        message: { role: "assistant", content: blocks },
+      } satisfies AssistantEntry);
+      continue;
+    }
+
+    if (recType === "tool.execution_start") {
+      const callId = data.toolCallId as string | undefined;
+      const name = (data.toolName as string) ?? "tool";
+      const args = (data.arguments as Record<string, unknown>) ?? {};
+      const id = callId ?? `${date.getTime()}-${name}`;
+      const toolUse: ToolUseBlock = {
+        type: "tool_use",
+        id,
+        name,
+        input: args,
+      };
+      const entry: AssistantEntry = {
+        type: "assistant",
+        ...baseEntry(rawCopy, timestamp, date, source),
+        message: { role: "assistant", content: [toolUse] },
+      };
+      entries.push(entry);
+      if (callId) {
+        toolUseById.set(callId, toolUse);
+        toolUseStartMs.set(callId, date.getTime());
+      }
+      continue;
+    }
+
+    if (recType === "tool.execution_complete") {
+      const callId = data.toolCallId as string | undefined;
+      const block = callId ? toolUseById.get(callId) : undefined;
+      if (block) {
+        const startMs = toolUseStartMs.get(callId!) ?? date.getTime();
+        const result = (data.result as CopilotToolResult | undefined) ?? {};
+        const telemetry = (data.toolTelemetry as CopilotToolTelemetry | undefined) ?? {};
+        const reportedMs =
+          telemetry.metrics?.commandTimeMs ?? telemetry.metrics?.durationMs ?? null;
+        const durationMs =
+          typeof reportedMs === "number" && reportedMs >= 0
+            ? reportedMs
+            : Math.max(0, date.getTime() - startMs);
+        const content = result.detailedContent ?? result.content ?? "";
+        block.result = {
+          timestamp,
+          timestampFormatted: formatTimestamp(date),
+          content: typeof content === "string" ? content : JSON.stringify(content),
+          durationMs,
+          durationFormatted: formatDuration(durationMs),
+        };
+        continue;
+      }
+      // Orphan tool result — preserve as system.
+      entries.push({
+        type: "system",
+        ...baseEntry(rawCopy, timestamp, date, source),
+        raw: rawCopy,
+      } satisfies GenericEntry);
+      continue;
+    }
+
+    // assistant.turn_start, assistant.turn_end, session.model_change,
+    // session.shutdown, and any unrecognized type — preserve raw so nothing is
+    // silently dropped, but keep them out of the structured user/assistant
+    // timeline (they're scaffolding events).
+    entries.push({
+      type: "system",
+      ...baseEntry(rawCopy, timestamp, date, source),
+      raw: rawCopy,
+    } satisfies GenericEntry);
+  }
+
+  if (entries.length > 500) await new Promise<void>((r) => setImmediate(r));
+  entries.sort((a, b) => a.timestampMs - b.timestampMs);
+
+  return { entries, rawLines, cwd };
+}
+
+// ── Public loader ──
+
+export interface CopilotSessionLogData {
+  entries: LogEntry[];
+  rawLines: Record<string, unknown>[];
+  cwd?: string;
+  filePath: string;
+}
+
+export async function getCopilotSessionLog(sessionId: string): Promise<CopilotSessionLogData | null> {
+  const filePath = findCopilotTranscript(sessionId);
+  if (!filePath) return null;
+  // findCopilotTranscript only proves existence at lookup time; the file can be
+  // removed/rotated before this readFile lands. Preserve the nullable contract
+  // instead of throwing into the session page.
+  let fileContent: string;
+  try {
+    fileContent = await readFile(filePath, "utf-8");
+  } catch {
+    return null;
+  }
+  const { entries, rawLines, cwd } = await parseCopilotLog(fileContent, "session");
+  // Fall back to workspace.yaml if events.jsonl didn't expose a session.start.
+  const resolvedCwd = cwd ?? readCopilotWorkspaceCwd(sessionId);
+  return { entries, rawLines, cwd: resolvedCwd, filePath };
+}
+
+export const getCachedCopilotSessionLog = runtimeCache(
+  (sessionId: string) => getCopilotSessionLog(sessionId),
+  60,
+  { maxSize: 50 },
+);
+
+// ── Test helpers ──
+
+/** For tests: read raw stat of the events.jsonl path, returning null on miss. */
+export function _statTranscript(sessionId: string): { mtimeMs: number } | null {
+  const path = findCopilotTranscript(sessionId);
+  if (!path) return null;
+  try {
+    const s = statSync(path);
+    return { mtimeMs: s.mtimeMs };
+  } catch {
+    return null;
+  }
+}
+
+/** For tests: list session IDs found in session-state/. */
+export function _listSessionIds(): string[] {
+  try {
+    return readdirSync(getCopilotSessionStateRoot(), { withFileTypes: true })
+      .filter((e) => e.isDirectory())
+      .map((e) => e.name);
+  } catch {
+    return [];
+  }
+}
+
+/** Surface a sync read variant used by lower-level code paths. */
+export function readCopilotTranscriptSync(sessionId: string): string | null {
+  const path = findCopilotTranscript(sessionId);
+  if (!path) return null;
+  try {
+    return readFileSync(path, "utf-8");
+  } catch {
+    return null;
+  }
+}

package/lib/cursor-projects.ts

@@ -0,0 +1,312 @@
+/**
+ * Cursor Agent CLI project discovery.
+ *
+ * Cursor stores per-session state under `~/.cursor/` (configurable via
+ * CURSOR_HOME). The exact subdirectory layout is not yet documented in
+ * cursor.com/docs/hooks; we probe the candidates Cursor has historically
+ * shipped (`agent-sessions/`, `conversations/`, `sessions/`) so this works
+ * across installs without a hard-coded version pin. Every candidate is a
+ * tolerant `safeReaddir` — a missing directory yields `[]`, never an
+ * exception.
+ *
+ * Each session directory is expected to contain at minimum a metadata file
+ * carrying the session's `cwd`. When a JSONL transcript is also present we
+ * surface the session under `/projects` keyed by encoded cwd so multiple
+ * stores naturally merge in `lib/projects.ts`.
+ *
+ * Refs: https://cursor.com/docs/hooks (env: CURSOR_PROJECT_DIR,
+ * CURSOR_TRANSCRIPT_PATH; transcript format intentionally unspecified).
+ */
+import { readdir, readFile, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { decodeFolderName, encodeFolderName } from "./paths";
+import type { ProjectFolder, SessionFile } from "./projects";
+import { runtimeCache } from "./runtime-cache";
+import { batchAll } from "./concurrency";
+import { formatDate } from "./format-date";
+import { logWarn } from "./logger";
+
+/** Legacy subdirectories under `~/.cursor/` that may carry per-session state
+ *  (cursor-agent ≤ 2026-04 ish — kept as a fallback). */
+const LEGACY_SESSION_ROOT_CANDIDATES = ["agent-sessions", "conversations", "sessions"] as const;
+
+/** Legacy filenames that may carry session-level metadata (cwd, model, …). */
+const META_FILE_CANDIDATES = ["meta.json", "session.json", "workspace.json", "workspace.yaml"] as const;
+
+/** Legacy filenames that may carry the JSONL transcript. */
+const LEGACY_TRANSCRIPT_FILE_CANDIDATES = ["events.jsonl", "transcript.jsonl", "messages.jsonl"] as const;
+
+/** New (2026-04+) layout: `~/.cursor/projects/<encoded-cwd>/agent-transcripts/<sessionId>/<sessionId>.jsonl`. */
+const NEW_PROJECTS_DIR = "projects";
+const NEW_AGENT_TRANSCRIPTS_DIR = "agent-transcripts";
+
+function getCursorHome(): string {
+  return process.env.CURSOR_HOME || join(homedir(), ".cursor");
+}
+
+interface CursorSessionMeta {
+  metaPath: string;
+  transcriptPath: string | null;
+  sessionId: string;
+  cwd: string;
+  fileMtime: Date;
+  hasTranscript: boolean;
+}
+
+async function safeReaddir(dir: string) {
+  try {
+    return await readdir(dir, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+}
+
+async function statMtime(path: string): Promise<Date | null> {
+  try {
+    return (await stat(path)).mtime;
+  } catch {
+    return null;
+  }
+}
+
+/** Parse a flat scalar for `cwd` from JSON-or-YAML metadata. Tries `JSON.parse`
+ *  first so escape sequences in JSON strings (e.g. Windows `C:\\Users\\...`) are
+ *  decoded, then falls back to a permissive YAML-ish regex when the file isn't
+ *  valid JSON. Tolerant on purpose: Cursor's metadata format is unspecified. */
+function parseCwdFromMetaText(text: string): string | undefined {
+  try {
+    const parsed = JSON.parse(text) as { cwd?: unknown };
+    if (typeof parsed.cwd === "string" && parsed.cwd.length > 0) return parsed.cwd;
+  } catch {
+    // Not JSON — fall through to the YAML-ish parser.
+  }
+  // YAML shape: `cwd: /path` (optionally quoted).
+  const yaml = text.match(/^\s*cwd\s*:\s*(.+?)\s*$/m);
+  if (yaml) {
+    const stripped = yaml[1].replace(/^['"]|['"]$/g, "");
+    if (stripped.length > 0) return stripped;
+  }
+  return undefined;
+}
+
+/** Try each candidate under `dir`; for metadata files we keep probing until one
+ *  yields a usable `cwd` (a stale `meta.json` shouldn't shadow a valid
+ *  `workspace.yaml`). Returns `{path, cwd}` for the first usable file, or null. */
+async function findFirstUsableMeta(
+  dir: string,
+  candidates: readonly string[],
+): Promise<{ path: string; cwd: string } | null> {
+  for (const name of candidates) {
+    const path = join(dir, name);
+    if ((await statMtime(path)) === null) continue;
+    let text: string;
+    try {
+      text = await readFile(path, "utf-8");
+    } catch {
+      continue;
+    }
+    const cwd = parseCwdFromMetaText(text);
+    if (cwd) return { path, cwd };
+  }
+  return null;
+}
+
+/** First existing path from `candidates` under `dir`. Used for transcript files
+ *  where existence is the only check we can perform without parsing JSONL. */
+async function findFirstExistingPath(dir: string, candidates: readonly string[]): Promise<string | null> {
+  for (const name of candidates) {
+    const path = join(dir, name);
+    if ((await statMtime(path)) !== null) return path;
+  }
+  return null;
+}
+
+async function scanCursorSessions(): Promise<CursorSessionMeta[]> {
+  const home = getCursorHome();
+  const newCandidates: { sessionId: string; dir: string; cwd: string }[] = [];
+  const legacyCandidates: { sessionId: string; dir: string }[] = [];
+
+  // New layout: ~/.cursor/projects/<encoded-cwd>/agent-transcripts/<sessionId>/<sessionId>.jsonl
+  // Cursor's project-folder encoding drops the leading slash (e.g.
+  // `home-u-repo` decodes to `/home/u/repo`, not `home/u/repo`). Re-add the
+  // leading slash for non-Windows-drive-letter results so the cwd is absolute.
+  const projectsRoot = join(home, NEW_PROJECTS_DIR);
+  const projectEntries = await safeReaddir(projectsRoot);
+  if (projectEntries) {
+    for (const proj of projectEntries) {
+      if (!proj.isDirectory()) continue;
+      const decoded = decodeFolderName(proj.name);
+      const cwd = decoded.startsWith("/") || /^[A-Za-z]:\//.test(decoded) ? decoded : `/${decoded}`;
+      const transcriptsRoot = join(projectsRoot, proj.name, NEW_AGENT_TRANSCRIPTS_DIR);
+      const sessionDirs = await safeReaddir(transcriptsRoot);
+      if (!sessionDirs) continue;
+      for (const sd of sessionDirs) {
+        if (!sd.isDirectory()) continue;
+        newCandidates.push({
+          sessionId: sd.name,
+          dir: join(transcriptsRoot, sd.name),
+          cwd,
+        });
+      }
+    }
+  }
+
+  // Legacy layout: ~/.cursor/{agent-sessions,conversations,sessions}/<sessionId>/
+  for (const sub of LEGACY_SESSION_ROOT_CANDIDATES) {
+    const root = join(home, sub);
+    const entries = await safeReaddir(root);
+    if (!entries) continue;
+    for (const e of entries) {
+      if (!e.isDirectory()) continue;
+      legacyCandidates.push({ sessionId: e.name, dir: join(root, e.name) });
+    }
+  }
+
+  if (newCandidates.length === 0 && legacyCandidates.length === 0) return [];
+
+  const settled = await batchAll(
+    [
+      ...newCandidates.map((c) => async (): Promise<CursorSessionMeta | null> => {
+        // Transcript file is `<sessionId>.jsonl` inside the dir.
+        const transcriptPath = join(c.dir, `${c.sessionId}.jsonl`);
+        const transcriptMtime = await statMtime(transcriptPath);
+        if (!transcriptMtime) return null;
+        return {
+          metaPath: c.dir, // No separate meta file; cwd is decoded from the parent dir name.
+          transcriptPath,
+          sessionId: c.sessionId,
+          cwd: c.cwd,
+          fileMtime: transcriptMtime,
+          hasTranscript: true,
+        };
+      }),
+      ...legacyCandidates.map((c) => async (): Promise<CursorSessionMeta | null> => {
+        const meta = await findFirstUsableMeta(c.dir, META_FILE_CANDIDATES);
+        if (!meta) return null;
+        const transcriptPath = await findFirstExistingPath(c.dir, LEGACY_TRANSCRIPT_FILE_CANDIDATES);
+        const transcriptMtime = transcriptPath ? await statMtime(transcriptPath) : null;
+        const metaMtime = await statMtime(meta.path);
+        const fileMtime =
+          transcriptMtime && metaMtime
+            ? new Date(Math.max(transcriptMtime.getTime(), metaMtime.getTime()))
+            : transcriptMtime ?? metaMtime ?? new Date(0);
+        return {
+          metaPath: meta.path,
+          transcriptPath,
+          sessionId: c.sessionId,
+          cwd: meta.cwd,
+          fileMtime,
+          hasTranscript: transcriptPath !== null,
+        };
+      }),
+    ],
+    16,
+  );
+  return settled
+    .filter((r): r is PromiseFulfilledResult<CursorSessionMeta | null> => r.status === "fulfilled")
+    .map((r) => r.value)
+    .filter((v): v is CursorSessionMeta => v !== null);
+}
+
+const cachedScan = runtimeCache(scanCursorSessions, 30);
+
+/** Returns one ProjectFolder per unique cwd discovered in Cursor transcripts. */
+export async function getCursorProjects(): Promise<ProjectFolder[]> {
+  let metas: CursorSessionMeta[];
+  try {
+    metas = await cachedScan();
+  } catch (error) {
+    logWarn("Failed to scan Cursor sessions:", error);
+    return [];
+  }
+
+  // Skip metadata-only sessions whose `/projects` row would click through to an
+  // empty session list (metasToSessionFiles also filters on hasTranscript).
+  const byCwd = new Map<string, { latest: Date; cwd: string }>();
+  for (const m of metas) {
+    if (!m.hasTranscript) continue;
+    const existing = byCwd.get(m.cwd);
+    if (!existing || m.fileMtime.getTime() > existing.latest.getTime()) {
+      byCwd.set(m.cwd, { latest: m.fileMtime, cwd: m.cwd });
+    }
+  }
+
+  const folders: ProjectFolder[] = [];
+  for (const { cwd, latest } of byCwd.values()) {
+    folders.push({
+      name: encodeFolderName(cwd),
+      path: cwd,
+      isDirectory: true,
+      lastModified: latest,
+      lastModifiedFormatted: formatDate(latest),
+      cli: ["cursor"],
+    });
+  }
+  folders.sort((a, b) => b.lastModified.getTime() - a.lastModified.getTime());
+  return folders;
+}
+
+function metasToSessionFiles(metas: CursorSessionMeta[]): SessionFile[] {
+  const files: SessionFile[] = metas
+    .filter((m) => m.hasTranscript && m.transcriptPath)
+    .map((m) => ({
+      name: m.sessionId,
+      path: m.transcriptPath!,
+      lastModified: m.fileMtime,
+      lastModifiedFormatted: formatDate(m.fileMtime),
+      sessionId: m.sessionId,
+      cli: "cursor",
+    }));
+  files.sort((a, b) => b.lastModified.getTime() - a.lastModified.getTime());
+  return files;
+}
+
+/** Returns SessionFile entries for every Cursor transcript whose cwd matches `cwd` exactly. */
+export async function getCursorSessionsForCwd(cwd: string): Promise<SessionFile[]> {
+  let metas: CursorSessionMeta[];
+  try {
+    metas = await cachedScan();
+  } catch (error) {
+    logWarn("Failed to scan Cursor sessions:", error);
+    return [];
+  }
+  return metasToSessionFiles(metas.filter((m) => m.cwd === cwd));
+}
+
+export interface CursorProjectByName {
+  cwd: string | null;
+  sessions: SessionFile[];
+}
+
+/**
+ * Looks up Cursor sessions for a project URL slug. `decodeFolderName` is lossy,
+ * so we re-encode each session's cwd and match in that direction. Returns both
+ * the canonical cwd and the matching sessions.
+ */
+export async function getCursorSessionsByEncodedName(name: string): Promise<CursorProjectByName> {
+  let metas: CursorSessionMeta[];
+  try {
+    metas = await cachedScan();
+  } catch (error) {
+    logWarn("Failed to scan Cursor sessions:", error);
+    return { cwd: null, sessions: [] };
+  }
+  const matches = metas.filter((m) => m.hasTranscript && encodeFolderName(m.cwd) === name);
+  return {
+    cwd: matches[0]?.cwd ?? null,
+    sessions: metasToSessionFiles(matches),
+  };
+}
+
+export const getCachedCursorProjects = runtimeCache(getCursorProjects, 30);
+export const getCachedCursorSessionsForCwd = runtimeCache(
+  (cwd: string) => getCursorSessionsForCwd(cwd),
+  30,
+  { maxSize: 50 },
+);
+export const getCachedCursorSessionsByEncodedName = runtimeCache(
+  (name: string) => getCursorSessionsByEncodedName(name),
+  30,
+  { maxSize: 50 },
+);