backpass 0.1.0

package/src/discovery/adapters/cursor-ide.js

@@ -0,0 +1,130 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { readJsonFile } from "./shared.js";
+import { openReadOnly, safeJsonParse } from "./sqlite.js";
+
+/**
+ * Cursor IDE - DEFERRED TO v1.1 (captain decision 3).
+ *
+ * The store is ~/Library/Application Support/Cursor/User/globalStorage/state.vscdb:
+ *   cursorDiskKV      `composerData:<id>` and `bubbleId:<composerId>:<bubbleId>` JSON
+ *   composerHeaders   (composerId, workspaceId, ...) - the only repo link there is
+ *
+ * The repo association runs composerHeaders.workspaceId -> workspaceStorage/<id>/
+ * workspace.json -> folder URI. On the machine this was designed against those
+ * workspaceId rows were empty, which makes association version-dependent and
+ * genuinely best-effort - hence the deferral.
+ *
+ * v1 ships this adapter behind --include-cursor-ide only. It never runs by default,
+ * every transcript it yields is labelled tier 3, and a failure here is a warning.
+ *
+ * TODO(v1.1): promote to a first-class adapter once a reliable composer -> workspace
+ * link exists across Cursor versions (and add Linux/Windows globalStorage paths).
+ */
+
+export const name = "cursor-ide";
+export const sqliteBacked = true;
+export const experimental = true;
+
+export function storeRoot() {
+  if (process.platform === "darwin") {
+    return path.join(os.homedir(), "Library", "Application Support", "Cursor", "User");
+  }
+  if (process.platform === "win32") {
+    return path.join(process.env.APPDATA || path.join(os.homedir(), "AppData", "Roaming"), "Cursor", "User");
+  }
+  return path.join(os.homedir(), ".config", "Cursor", "User");
+}
+
+function globalDbPath() {
+  return path.join(storeRoot(), "globalStorage", "state.vscdb");
+}
+
+/** workspaceId -> folder path, read from workspaceStorage/<id>/workspace.json. */
+function workspaceFolders() {
+  const dir = path.join(storeRoot(), "workspaceStorage");
+  const map = new Map();
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return map;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const meta = readJsonFile(path.join(dir, entry.name, "workspace.json"));
+    const folder = meta?.folder;
+    if (typeof folder !== "string") continue;
+    map.set(entry.name, decodeURIComponent(folder.replace(/^file:\/\//, "")));
+  }
+  return map;
+}
+
+export async function discover({ cutoffMs }) {
+  const db = await openReadOnly(globalDbPath());
+  if (!db) return [];
+
+  try {
+    const folders = workspaceFolders();
+    let headers = [];
+    try {
+      headers = db.prepare("SELECT composerId, workspaceId FROM composerHeaders").all();
+    } catch {
+      // Older/newer Cursor builds may not have this table at all.
+      return [];
+    }
+
+    const out = [];
+    for (const header of headers) {
+      const cwd = header.workspaceId ? folders.get(header.workspaceId) : null;
+      if (!cwd) continue; // No usable repo link - the deferral in one line.
+      const row = db.prepare("SELECT value FROM cursorDiskKV WHERE key = ?").get(`composerData:${header.composerId}`);
+      const data = row ? safeJsonParse(row.value) : null;
+      const updatedAt = data?.lastUpdatedAt || data?.createdAt || 0;
+      if (cutoffMs && updatedAt && updatedAt < cutoffMs) continue;
+
+      out.push({
+        key: `cursor-ide:${header.composerId}`,
+        id: header.composerId,
+        path: globalDbPath(),
+        cwd,
+        remotes: [],
+        startedAt: data?.createdAt || null,
+        mtimeMs: updatedAt,
+        bytes: 0,
+        model: null,
+        experimental: true,
+        extra: { composerId: header.composerId },
+      });
+    }
+    return out;
+  } finally {
+    db.close();
+  }
+}
+
+export async function read(ref) {
+  const db = await openReadOnly(globalDbPath());
+  if (!db) return { events: [], model: null };
+
+  try {
+    const composerId = ref.extra?.composerId || ref.id;
+    const rows = db
+      .prepare("SELECT key, value FROM cursorDiskKV WHERE key LIKE ? ORDER BY key")
+      .all(`bubbleId:${composerId}:%`);
+
+    const events = [];
+    for (const row of rows) {
+      const bubble = safeJsonParse(row.value);
+      if (!bubble) continue;
+      const role = bubble.type === 1 ? "user" : "assistant";
+      const text = bubble.text || bubble.richText || "";
+      if (typeof text === "string" && text.trim()) events.push({ kind: "message", role, text });
+    }
+    return { events, model: null };
+  } finally {
+    db.close();
+  }
+}

package/src/discovery/adapters/grok.js

@@ -0,0 +1,107 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { attachToolResults, contentToEvents, home, listDirs, readJsonFile, readJsonl, statOrNull } from "./shared.js";
+
+/**
+ * grok: ~/.grok/sessions/<url-encoded-cwd>/<session-uuid>/
+ *         chat_history.jsonl  - the conversation
+ *         summary.json        - {info:{cwd}, git_root_dir, git_remotes[], head_branch, ...}
+ *
+ * `git_remotes` is recorded at session start, so grok reaches tier 2 for dead worktrees.
+ * The unit of discovery is the session directory rather than a single file.
+ */
+
+export const name = "grok";
+
+export function storeRoot() {
+  return home(".grok", "sessions");
+}
+
+export function enumerate() {
+  const out = [];
+  for (const cwdDir of listDirs(storeRoot())) {
+    for (const sessionDir of listDirs(cwdDir)) {
+      const chat = path.join(sessionDir, "chat_history.jsonl");
+      const stat = statOrNull(chat);
+      if (!stat) continue;
+      out.push({ key: sessionDir, path: sessionDir, chatPath: chat, mtimeMs: stat.mtimeMs, bytes: stat.size });
+    }
+  }
+  return out;
+}
+
+export function classify(candidate) {
+  const summary = readJsonFile(path.join(candidate.path, "summary.json"));
+  const cwd = summary?.info?.cwd ?? decodeDirName(path.basename(path.dirname(candidate.path)));
+  if (!cwd) return null;
+  return {
+    id: summary?.info?.id || path.basename(candidate.path),
+    cwd,
+    gitRoot: summary?.git_root_dir || null,
+    gitBranch: summary?.head_branch || null,
+    remotes: Array.isArray(summary?.git_remotes) ? summary.git_remotes : [],
+    startedAt: summary?.created_at ? Date.parse(summary.created_at) : candidate.mtimeMs,
+    model: summary?.current_model_id || null,
+    extra: { chatPath: candidate.chatPath || path.join(candidate.path, "chat_history.jsonl") },
+  };
+}
+
+function decodeDirName(encoded) {
+  try {
+    return decodeURIComponent(encoded);
+  } catch {
+    return null;
+  }
+}
+
+export function read(ref) {
+  const chatPath = ref.extra?.chatPath || path.join(ref.path, "chat_history.jsonl");
+  if (!fs.existsSync(chatPath)) return { events: [], model: null };
+
+  const entries = readJsonl(chatPath);
+  const events = [];
+  let model = null;
+
+  for (const entry of entries) {
+    switch (entry.type) {
+      case "user":
+        contentToEvents("user", entry.content, events);
+        break;
+      case "assistant":
+        model = model || entry.model_id || null;
+        contentToEvents("assistant", entry.content, events);
+        // grok hangs tool calls off the assistant record rather than emitting blocks.
+        for (const call of entry.tool_calls || []) {
+          events.push({
+            kind: "tool",
+            name: call.name,
+            input: parseMaybeJson(call.arguments ?? call.input),
+            pendingId: call.id,
+          });
+        }
+        break;
+      case "tool_result":
+        events.push({ kind: "tool-result", id: entry.tool_call_id ?? entry.id, result: entry.content });
+        break;
+      default:
+        break;
+    }
+  }
+
+  return { events: attachToolResults(events), model };
+}
+
+/** Exported for the raw-transcript escape hatch: the analysis agent opens this file. */
+export function rawPath(ref) {
+  return ref.extra?.chatPath || path.join(ref.path, "chat_history.jsonl");
+}
+
+function parseMaybeJson(value) {
+  if (typeof value !== "string") return value;
+  try {
+    return JSON.parse(value);
+  } catch {
+    return value;
+  }
+}

package/src/discovery/adapters/opencode.js

@@ -0,0 +1,151 @@
+import path from "node:path";
+
+import { home, listDirs, readJsonFile, statOrNull } from "./shared.js";
+import { openReadOnly, safeJsonParse } from "./sqlite.js";
+
+/**
+ * opencode: ~/.local/share/opencode/opencode.db (sqlite)
+ *
+ *   project(id, worktree)             - one row per project root
+ *   session(id, project_id, directory, title, time_created)
+ *   message(id, session_id, data)     - data is JSON: {role, model, time, ...}
+ *   part(id, message_id, session_id, data) - data is JSON: {type: text|tool|reasoning|...}
+ *
+ * This is the best-behaved store of the six: association is a SQL predicate on
+ * `session.directory`, deleted worktrees included, and both listing and reading are
+ * indexed. Older opencode versions used file storage under `storage/`; that layout is
+ * handled as a fallback so long-lived machines still yield transcripts.
+ */
+
+export const name = "opencode";
+export const sqliteBacked = true;
+
+export function storeRoot() {
+  return home(".local", "share", "opencode");
+}
+
+export function dbPath() {
+  return path.join(storeRoot(), "opencode.db");
+}
+
+/**
+ * Discovery is direct: one query returns every session with its directory, and the
+ * caller applies the shared association tiers.
+ */
+export async function discover({ cutoffMs }) {
+  const db = await openReadOnly(dbPath());
+  if (!db) return legacyDiscover({ cutoffMs });
+
+  try {
+    const rows = db
+      .prepare(
+        `SELECT s.id AS id, s.directory AS directory, s.title AS title,
+                s.time_created AS time_created, s.time_updated AS time_updated,
+                p.worktree AS worktree
+           FROM session s
+           LEFT JOIN project p ON p.id = s.project_id
+          WHERE (? IS NULL OR s.time_updated >= ?)`,
+      )
+      .all(cutoffMs ?? null, cutoffMs ?? 0);
+
+    return rows.map((row) => ({
+      key: `opencode:${row.id}`,
+      id: row.id,
+      path: dbPath(),
+      cwd: row.directory,
+      gitRoot: row.worktree || null,
+      gitBranch: null,
+      remotes: [],
+      title: row.title || null,
+      startedAt: Number(row.time_created) || null,
+      mtimeMs: Number(row.time_updated) || Number(row.time_created) || 0,
+      bytes: 0,
+      model: null,
+      extra: { sessionId: row.id },
+    }));
+  } finally {
+    db.close();
+  }
+}
+
+export async function read(ref) {
+  const db = await openReadOnly(dbPath());
+  if (!db) return legacyRead();
+
+  try {
+    const sessionId = ref.extra?.sessionId || ref.id;
+    const messages = db
+      .prepare("SELECT id, data FROM message WHERE session_id = ? ORDER BY time_created, id")
+      .all(sessionId);
+    const parts = db
+      .prepare("SELECT message_id, data FROM part WHERE session_id = ? ORDER BY time_created, id")
+      .all(sessionId);
+
+    const partsByMessage = new Map();
+    for (const part of parts) {
+      if (!partsByMessage.has(part.message_id)) partsByMessage.set(part.message_id, []);
+      partsByMessage.get(part.message_id).push(safeJsonParse(part.data));
+    }
+
+    const events = [];
+    let model = null;
+
+    for (const message of messages) {
+      const data = safeJsonParse(message.data) || {};
+      const role = data.role === "user" ? "user" : "assistant";
+      model = model || data.modelID || data.model?.modelID || null;
+
+      const texts = [];
+      for (const part of partsByMessage.get(message.id) || []) {
+        if (!part) continue;
+        if (part.type === "text" && part.text) {
+          texts.push(part.text);
+        } else if (part.type === "tool") {
+          events.push({
+            kind: "tool",
+            name: part.tool || part.name,
+            input: part.state?.input ?? part.input,
+            result: part.state?.output ?? part.output,
+            status: part.state?.status,
+          });
+        }
+        // reasoning / step-start / step-finish / patch / file parts carry no loss signal.
+      }
+      if (texts.length) events.push({ kind: "message", role, text: texts.join("\n") });
+    }
+
+    return { events, model };
+  } finally {
+    db.close();
+  }
+}
+
+/** Pre-sqlite opencode kept JSON files under storage/. Best-effort, never fatal. */
+function legacyDiscover({ cutoffMs }) {
+  const projectsDir = path.join(storeRoot(), "storage", "project");
+  const out = [];
+  for (const dir of listDirs(projectsDir)) {
+    const meta = readJsonFile(path.join(dir, "project.json"));
+    const stat = statOrNull(dir);
+    if (!meta?.worktree || !stat) continue;
+    if (cutoffMs && stat.mtimeMs < cutoffMs) continue;
+    out.push({
+      key: `opencode-legacy:${dir}`,
+      id: path.basename(dir),
+      path: dir,
+      cwd: meta.worktree,
+      remotes: [],
+      startedAt: stat.birthtimeMs || stat.mtimeMs,
+      mtimeMs: stat.mtimeMs,
+      bytes: 0,
+      extra: { legacy: true },
+    });
+  }
+  return out;
+}
+
+function legacyRead() {
+  // The legacy layout stores messages per project in a shape that changed across
+  // releases; rather than guess, report an empty trace so the run stays fail-soft.
+  return { events: [], model: null };
+}

package/src/discovery/adapters/pi.js

@@ -0,0 +1,87 @@
+import path from "node:path";
+
+import {
+  attachToolResults,
+  contentToEvents,
+  home,
+  listDirs,
+  listFiles,
+  parseJsonLine,
+  readHeadLines,
+  readJsonl,
+  statOrNull,
+} from "./shared.js";
+
+/**
+ * pi: ~/.pi/agent/sessions/<escaped-cwd>/<ISO-ts>_<uuid>.jsonl
+ *
+ * Line 1 is `{type:"session", cwd, id}`. Entries form a parent/child tree but arrive in
+ * order, so a linear read is faithful. `model_change` / `thinking_level_change` records
+ * give the model actually used. No remote is recorded - dead worktrees reach tier 3 only.
+ */
+
+export const name = "pi";
+
+export function storeRoot() {
+  return home(".pi", "agent", "sessions");
+}
+
+export function enumerate() {
+  const out = [];
+  for (const dir of listDirs(storeRoot())) {
+    for (const file of listFiles(dir, ".jsonl")) {
+      const stat = statOrNull(file);
+      if (!stat) continue;
+      out.push({ key: file, path: file, mtimeMs: stat.mtimeMs, bytes: stat.size });
+    }
+  }
+  return out;
+}
+
+export function classify(candidate) {
+  const [first] = readHeadLines(candidate.path, 1);
+  const entry = first && parseJsonLine(first);
+  if (!entry || entry.type !== "session" || !entry.cwd) return null;
+  return {
+    id: entry.id || path.basename(candidate.path, ".jsonl"),
+    cwd: entry.cwd,
+    gitBranch: null,
+    remotes: [],
+    startedAt: entry.timestamp ? Date.parse(entry.timestamp) : candidate.mtimeMs,
+    model: null,
+  };
+}
+
+export function read(ref) {
+  const entries = readJsonl(ref.path);
+  const events = [];
+  let model = null;
+
+  for (const entry of entries) {
+    if (entry.type === "model_change") {
+      model = entry.modelId || model;
+      continue;
+    }
+    if (entry.type !== "message" || !entry.message) continue;
+    const message = entry.message;
+    const role = message.role;
+
+    if (role === "toolResult") {
+      events.push({ kind: "tool-result", id: message.toolCallId ?? message.id, result: textOf(message.content) });
+      continue;
+    }
+    if (role !== "user" && role !== "assistant") continue;
+    contentToEvents(role, message.content, events);
+  }
+
+  return { events: attachToolResults(events), model };
+}
+
+function textOf(content) {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return content;
+  return content
+    .map((b) => (typeof b === "string" ? b : (b?.text ?? "")))
+    .filter(Boolean)
+    .join("\n");
+}

package/src/discovery/adapters/shared.js

@@ -0,0 +1,195 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+/** Read at most `maxLines` lines (or `maxBytes`) from the head of a file. */
+export function readHeadLines(file, maxLines = 1, maxBytes = 512 * 1024) {
+  let fd;
+  try {
+    fd = fs.openSync(file, "r");
+    const size = fs.fstatSync(fd).size;
+    const length = Math.min(size, maxBytes);
+    const buffer = Buffer.alloc(length);
+    fs.readSync(fd, buffer, 0, length, 0);
+    const text = buffer.toString("utf8");
+    const lines = text.split("\n");
+    // A final partial line is only safe to use when we read the whole file.
+    if (length < size) lines.pop();
+    return lines.filter((l) => l.trim()).slice(0, maxLines);
+  } catch {
+    return [];
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+  }
+}
+
+export function parseJsonLine(line) {
+  try {
+    return JSON.parse(line);
+  } catch {
+    return null;
+  }
+}
+
+export function readJsonFile(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+export function readJsonl(file, { maxBytes = 64 * 1024 * 1024 } = {}) {
+  let text;
+  try {
+    const stat = fs.statSync(file);
+    if (stat.size > maxBytes) {
+      // Very large sessions are read tail-first: recent turns carry the loss signal.
+      const fd = fs.openSync(file, "r");
+      const buffer = Buffer.alloc(maxBytes);
+      fs.readSync(fd, buffer, 0, maxBytes, stat.size - maxBytes);
+      fs.closeSync(fd);
+      text = buffer.toString("utf8");
+      text = text.slice(text.indexOf("\n") + 1);
+    } else {
+      text = fs.readFileSync(file, "utf8");
+    }
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const line of text.split("\n")) {
+    if (!line.trim()) continue;
+    const value = parseJsonLine(line);
+    if (value) out.push(value);
+  }
+  return out;
+}
+
+export function statOrNull(file) {
+  try {
+    return fs.statSync(file);
+  } catch {
+    return null;
+  }
+}
+
+export function listDirs(dir) {
+  try {
+    return fs
+      .readdirSync(dir, { withFileTypes: true })
+      .filter((e) => e.isDirectory())
+      .map((e) => path.join(dir, e.name));
+  } catch {
+    return [];
+  }
+}
+
+export function listFiles(dir, suffix) {
+  try {
+    return fs
+      .readdirSync(dir, { withFileTypes: true })
+      .filter((e) => e.isFile() && (!suffix || e.name.endsWith(suffix)))
+      .map((e) => path.join(dir, e.name));
+  } catch {
+    return [];
+  }
+}
+
+export function home(...segments) {
+  return path.join(os.homedir(), ...segments);
+}
+
+/**
+ * Normalize an assistant/user `content` value into distiller events. Every harness
+ * settled on some variant of "string, or array of typed blocks", so one tolerant
+ * reader covers claude, codex, pi, grok and cursor with adapter-specific tweaks
+ * layered on top.
+ */
+export function contentToEvents(role, content, events) {
+  if (content === null || content === undefined) return;
+  if (typeof content === "string") {
+    if (content.trim()) events.push({ kind: "message", role, text: content });
+    return;
+  }
+  if (!Array.isArray(content)) {
+    if (typeof content.text === "string") events.push({ kind: "message", role, text: content.text });
+    return;
+  }
+  const texts = [];
+  for (const block of content) {
+    if (!block || typeof block !== "object") {
+      if (typeof block === "string") texts.push(block);
+      continue;
+    }
+    switch (block.type) {
+      case "text":
+      case "input_text":
+      case "output_text":
+        if (block.text) texts.push(block.text);
+        break;
+      case "tool_use":
+      case "toolCall":
+        events.push({
+          kind: "tool",
+          name: block.name,
+          input: block.input ?? block.arguments,
+          pendingId: block.id ?? block.call_id,
+        });
+        break;
+      case "tool_result":
+      case "toolResult":
+        events.push({
+          kind: "tool-result",
+          id: block.tool_use_id ?? block.id,
+          result: block.content ?? block.output ?? block.text,
+          status: block.is_error ? "error" : "completed",
+        });
+        break;
+      case "thinking":
+      case "reasoning":
+        break;
+      default:
+        if (typeof block.text === "string") texts.push(block.text);
+        break;
+    }
+  }
+  if (texts.length) {
+    const joined = texts.join("\n").trim();
+    if (joined) events.push({ kind: "message", role, text: joined });
+  }
+}
+
+/**
+ * Fold `tool-result` events back into the `tool` call they answer, so the distiller
+ * emits one line per tool call rather than two.
+ */
+export function attachToolResults(events) {
+  const out = [];
+  const byId = new Map();
+  for (const event of events) {
+    if (event.kind === "tool") {
+      out.push(event);
+      if (event.pendingId) byId.set(event.pendingId, event);
+      continue;
+    }
+    if (event.kind === "tool-result") {
+      const target = event.id && byId.get(event.id);
+      if (target) {
+        target.result = event.result;
+        target.status = event.status;
+      } else {
+        // Orphan result (truncated log, or a harness that does not correlate ids).
+        const last = [...out].reverse().find((e) => e.kind === "tool" && e.result === undefined);
+        if (last) {
+          last.result = event.result;
+          last.status = event.status;
+        }
+      }
+      continue;
+    }
+    out.push(event);
+  }
+  for (const event of out) delete event.pendingId;
+  return out;
+}