backpass 0.1.1 → 0.1.2

package/README.md

@@ -32,7 +32,7 @@ The loop only closes when a human happens to remember a failure and edits the fi
 what happened in them, and proposes evidence-backed edits to your memory file - under a
 token budget, gated by you.
 
-- **Local-first** - Reads the transcript stores of six agent harnesses directly from disk.
+- **Local-first** - Reads the transcript stores of seven agent harnesses directly from disk.
   No API, no upload; transcripts never leave your machine except into an agent you already
   authenticated, and obvious secrets are redacted before they do.
 - **Evidence-gated** - Every proposed edit carries verbatim quotes from real sessions, a
@@ -78,16 +78,20 @@ backpass apply     # review each edit, accept or reject, then write
 
 ### 1. Collect samples - which sessions belong to this repo
 
-backpass reads the local transcript stores of six harnesses directly. No API, no upload.
+backpass reads the local transcript stores of seven harnesses directly. No API, no upload.
 
-| Harness        | Store                                          | Repo tie                              |
-| -------------- | ---------------------------------------------- | ------------------------------------- |
-| **claude**     | `~/.claude/projects/<munged-cwd>/<uuid>.jsonl` | per-line `cwd`                        |
-| **codex**      | `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl` | `cwd` + recorded `git.repository_url` |
-| **pi**         | `~/.pi/agent/sessions/<escaped-cwd>/*.jsonl`   | session-header `cwd`                  |
-| **opencode**   | `~/.local/share/opencode/opencode.db` (sqlite) | `session.directory`                   |
-| **grok**       | `~/.grok/sessions/<encoded-cwd>/<uuid>/`       | `summary.json` `cwd` + `git_remotes`  |
-| **cursor CLI** | `~/.cursor/chats/<md5(cwd)>/<uuid>/`           | `meta.json` `cwd`                     |
+| Harness        | Store                                          | Repo tie                                |
+| -------------- | ---------------------------------------------- | --------------------------------------- |
+| **claude**     | `~/.claude/projects/<munged-cwd>/<uuid>.jsonl` | per-line `cwd`                          |
+| **codex**      | `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl` | `cwd` + recorded `git.repository_url`   |
+| **pi**         | `~/.pi/agent/sessions/<escaped-cwd>/*.jsonl`   | session-header `cwd`                    |
+| **opencode**   | `~/.local/share/opencode/opencode.db` (sqlite) | `session.directory`                     |
+| **grok**       | `~/.grok/sessions/<encoded-cwd>/<uuid>/`       | `summary.json` `cwd` + `git_remotes`    |
+| **cursor CLI** | `~/.cursor/chats/<md5(cwd)>/<uuid>/`           | `meta.json` `cwd`                       |
+| **hermes**     | `~/.hermes/state.db` (sqlite)                  | CLI prompt cwd / ACP `model_config.cwd` |
+
+Hermes collection includes CLI and ACP sessions only. Gateway, cron, and WhatsApp sessions
+are excluded because their recorded cwd belongs to the shared gateway process, not a project.
 
 Association runs in three tiers:
 
@@ -355,7 +359,7 @@ CLI flags on top:
     ]
   },
   "discovery": {
-    "harnesses": ["claude", "codex", "pi", "opencode", "grok", "cursor"],
+    "harnesses": ["claude", "codex", "pi", "opencode", "grok", "cursor", "hermes"],
     "since": "30d",
     "worktreeGlobs": [],
     "minUserTurns": 2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backpass",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "packageManager": "pnpm@11.5.0",
   "description": "Gradient descent for your agent memory - analyzes past agent session transcripts and proposes evidence-backed edits to AGENTS.md / CLAUDE.md",
   "type": "module",

package/src/cli.js

@@ -83,7 +83,7 @@ COMMANDS
 COLLECT SAMPLES
   --since <dur>            only sessions newer than this (30d, 12h, 2w, all)  [30d]
   --harness <a,b>          limit to these harnesses
-                           (claude, codex, pi, opencode, grok, cursor)
+                           (claude, codex, pi, opencode, grok, cursor, hermes)
   --strict                 deterministic associations only (tiers 1 and 2)
   --include-cursor-ide     also scan the Cursor IDE store (best-effort, v1.1 preview)
   --limit <n>              analyze at most N transcripts this run (newest first)

package/src/config.js

@@ -7,7 +7,7 @@ import { UserError, warn } from "./logger.js";
 export const CONFIG_FILENAME = ".backpassrc.json";
 export const STATE_DIRNAME = ".backpass";
 
-export const ALL_HARNESSES = ["claude", "codex", "pi", "opencode", "grok", "cursor"];
+export const ALL_HARNESSES = ["claude", "codex", "pi", "opencode", "grok", "cursor", "hermes"];
 /** Cursor IDE is deferred to v1.1 and only ever runs behind --include-cursor-ide. */
 export const OPT_IN_HARNESSES = ["cursor-ide"];
 

package/src/discovery/adapters/hermes.js

@@ -0,0 +1,222 @@
+import path from "node:path";
+
+import { home, contentToEvents, attachToolResults } from "./shared.js";
+import { openReadOnly, safeJsonParse } from "./sqlite.js";
+
+/**
+ * hermes: ~/.hermes/state.db (sqlite)
+ *
+ * Observed schema version 13 (upstream is 26; SELECT named columns so additive
+ * columns are tolerated). Hermes has no cwd, git branch, or git remote column.
+ *
+ * Association is recovered only for source in ('cli', 'acp'):
+ *   acp - model_config.cwd when it is an absolute path
+ *   cli - first `Current working directory:` / `Working directory:` line in
+ *         system_prompt
+ * Gateway / cron / whatsapp sessions are skipped: their prompt cwd is the
+ * gateway process cwd, not a project, and would pin unrelated sessions to one
+ * repo. Sessions with no recoverable cwd are skipped.
+ *
+ * Timestamps are epoch seconds; backpass uses milliseconds (x1000).
+ * Structured content uses a `\x00json:` prefix; node:sqlite truncates TEXT at
+ * NUL, so message content is read as BLOB and decoded.
+ * JSONL leftovers under ~/.hermes/sessions/ are abandoned and not read.
+ * Honor HERMES_HOME; do not walk profile directories.
+ */
+
+export const name = "hermes";
+export const sqliteBacked = true;
+
+const CLI_ACP = new Set(["cli", "acp"]);
+const JSON_PREFIX = "\x00json:";
+const CWD_LINE = /^(?:Current working directory|Working directory):\s*(.+)$/m;
+
+export function storeRoot() {
+  return process.env.HERMES_HOME || home(".hermes");
+}
+
+export function dbPath() {
+  return path.join(storeRoot(), "state.db");
+}
+
+function toMs(epochSeconds) {
+  const n = Number(epochSeconds);
+  return Number.isFinite(n) ? Math.round(n * 1000) : null;
+}
+
+function looksAbsolute(value) {
+  return typeof value === "string" && value.length > 0 && path.isAbsolute(value);
+}
+
+function cwdFromConfig(raw) {
+  const parsed = typeof raw === "string" ? safeJsonParse(raw) : raw;
+  return looksAbsolute(parsed?.cwd) ? parsed.cwd : null;
+}
+
+function cwdFromPrompt(prompt) {
+  if (typeof prompt !== "string" || !prompt) return null;
+  const match = prompt.match(CWD_LINE);
+  if (!match) return null;
+  const cwd = match[1].trim();
+  return looksAbsolute(cwd) ? cwd : null;
+}
+
+function recoverCwd(row, source) {
+  if (source === "acp") return cwdFromConfig(row.model_config);
+  if (source === "cli") return cwdFromPrompt(row.system_prompt);
+  return null;
+}
+
+function activeMessageFilter(db, alias = "") {
+  const hasActive = db
+    .prepare("PRAGMA table_info(messages)")
+    .all()
+    .some((column) => column.name === "active");
+  return hasActive ? ` AND ${alias}active = 1` : "";
+}
+
+/**
+ * Discovery is one indexed query. The caller applies the shared association
+ * tiers and handles schema errors per harness. A missing DB yields an empty list.
+ * @param {{ cutoffMs?: number }} [options]
+ */
+export async function discover({ cutoffMs } = {}) {
+  const db = await openReadOnly(dbPath());
+  if (!db) return [];
+
+  const cutoffSec = cutoffMs == null ? null : cutoffMs / 1000;
+  try {
+    const activeFilter = activeMessageFilter(db, "m.");
+    const rows = db
+      .prepare(
+        `SELECT s.id, s.source, s.model, s.model_config, s.system_prompt, s.title,
+                s.started_at, s.ended_at,
+                MAX(s.started_at,
+                    COALESCE(s.ended_at, s.started_at),
+                    COALESCE((SELECT MAX(m.timestamp)
+                                FROM messages m
+                               WHERE m.session_id = s.id${activeFilter}),
+                             s.started_at)) AS activity_at
+           FROM sessions s
+          WHERE lower(s.source) IN ('cli', 'acp')
+            AND (? IS NULL OR
+                 MAX(s.started_at,
+                     COALESCE(s.ended_at, s.started_at),
+                     COALESCE((SELECT MAX(m.timestamp)
+                                 FROM messages m
+                                WHERE m.session_id = s.id${activeFilter}),
+                              s.started_at)) >= ?)`,
+      )
+      .all(cutoffSec, cutoffSec ?? 0);
+
+    const out = [];
+    for (const row of rows) {
+      const source = String(row.source || "").toLowerCase();
+      if (!CLI_ACP.has(source)) continue;
+      const cwd = recoverCwd(row, source);
+      if (!cwd) continue;
+      const startedAt = toMs(row.started_at);
+      const activityAt = toMs(row.activity_at);
+      out.push({
+        key: `hermes:${row.id}`,
+        id: row.id,
+        path: dbPath(),
+        cwd,
+        gitRoot: null,
+        gitBranch: null,
+        remotes: [],
+        title: row.title || null,
+        startedAt,
+        mtimeMs: activityAt || startedAt || 0,
+        bytes: 0,
+        model: row.model || null,
+        extra: { sessionId: row.id, source },
+      });
+    }
+    return out;
+  } finally {
+    db.close();
+  }
+}
+
+/** node:sqlite truncates TEXT at a NUL, so `\x00json:` payloads must be read as BLOB. */
+function sqliteText(value) {
+  if (value == null) return value;
+  if (typeof value === "string") return value;
+  if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) {
+    return new TextDecoder("utf8").decode(value);
+  }
+  return String(value);
+}
+
+function decodeContent(content) {
+  const text = sqliteText(content);
+  if (typeof text !== "string") return content;
+  if (!text.startsWith(JSON_PREFIX)) return text;
+  const parsed = safeJsonParse(text.slice(JSON_PREFIX.length));
+  return parsed == null ? text : parsed;
+}
+
+function emitTools(raw, events, idAlias) {
+  const text = sqliteText(raw);
+  const parsed = typeof text === "string" ? safeJsonParse(text) : text;
+  if (!Array.isArray(parsed)) return;
+  for (const call of parsed) {
+    if (!call || typeof call !== "object") continue;
+    const fn = call.function && typeof call.function === "object" ? call.function : {};
+    const name = fn.name || call.name;
+    let input = fn.arguments ?? call.arguments;
+    if (typeof input === "string") {
+      const parsedInput = safeJsonParse(input);
+      if (parsedInput !== null) input = parsedInput;
+    }
+    const pendingId = call.id || call.call_id;
+    if (call.id) idAlias.set(call.id, pendingId);
+    if (call.call_id) idAlias.set(call.call_id, pendingId);
+    events.push({ kind: "tool", name, input, pendingId });
+  }
+}
+
+export async function read(ref) {
+  const db = await openReadOnly(dbPath());
+  if (!db) return { events: [], model: ref.model || null };
+
+  try {
+    const sessionId = ref.extra?.sessionId || ref.id;
+    const activeFilter = activeMessageFilter(db);
+    const rows = db
+      .prepare(
+        `SELECT role, CAST(content AS BLOB) AS content, tool_call_id, tool_calls, tool_name
+           FROM messages
+          WHERE session_id = ?${activeFilter}
+          ORDER BY timestamp, id`,
+      )
+      .all(sessionId);
+
+    const events = [];
+    const idAlias = new Map();
+    for (const row of rows) {
+      const role = row.role;
+      if (role === "session_meta") continue;
+      const content = decodeContent(row.content);
+      if (role === "user" || role === "assistant") {
+        contentToEvents(role, content, events);
+        if (role === "assistant") emitTools(row.tool_calls, events, idAlias);
+        continue;
+      }
+      if (role === "tool") {
+        events.push({
+          kind: "tool-result",
+          id: idAlias.get(row.tool_call_id) || row.tool_call_id,
+          result: content,
+          status: "completed",
+        });
+      }
+    }
+    return { events: attachToolResults(events), model: ref.model || null };
+  } catch {
+    return { events: [], model: ref.model || null };
+  } finally {
+    db.close();
+  }
+}

package/src/discovery/adapters/opencode.js

@@ -11,7 +11,7 @@ import { openReadOnly, safeJsonParse } from "./sqlite.js";
  *   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
+ * This is the best-behaved store: 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.

package/src/discovery/index.js

@@ -3,6 +3,7 @@ import * as codex from "./adapters/codex.js";
 import * as pi from "./adapters/pi.js";
 import * as grok from "./adapters/grok.js";
 import * as opencode from "./adapters/opencode.js";
+import * as hermes from "./adapters/hermes.js";
 import * as cursorCli from "./adapters/cursor-cli.js";
 import * as cursorIde from "./adapters/cursor-ide.js";
 
@@ -18,6 +19,7 @@ export const ADAPTERS = {
   pi,
   grok,
   opencode,
+  hermes,
   cursor: cursorCli,
   "cursor-ide": cursorIde,
 };
@@ -34,8 +36,8 @@ export function getAdapter(harness) {
  * Re-scans are then O(new files) - which matters: codex alone had 10,317 rollouts on
  * the machine this was designed against.
  *
- * SQLite-backed stores (opencode, cursor IDE) answer the same question with one indexed
- * query, so they skip the cache entirely.
+ * SQLite-backed stores (opencode, hermes, cursor IDE) answer the same question with one
+ * indexed query, so they skip the cache entirely.
  *
  * Every harness is fail-soft: a store that is missing, unreadable, or has drifted into
  * an unrecognised format produces a named warning and is skipped, never a failed run.

package/src/discovery/self.js

@@ -16,7 +16,7 @@ import { SELF_SESSION_SENTINEL } from "../prompts.js";
  *
  * The check reads only the head of the file and keys on the JSON-encoded user text as
  * every file-backed harness records it (`"text":"..."` / `"content":"..."` /
- * `"message":"..."`). SQLite-backed stores (opencode, cursor IDE) have no file to
+ * `"message":"..."`). SQLite-backed stores (opencode, hermes, cursor IDE) have no file to
  * inspect and acpx does not drive them, so they are passed through.
  */
 

package/src/tui/render.js

@@ -33,6 +33,7 @@ const HARNESS_HUES = {
   grok: "magenta",
   cursor: "blue",
   "cursor-ide": "blue",
+  hermes: "yellow",
 };
 
 /**
@@ -302,7 +303,7 @@ function discoverDetail(state, theme, width, spin) {
       const scanned = `${formatCount(h.scanned)} sessions`;
       const fresh = h.newCount > 0 || h.scanned > 0 ? ` · ${formatCount(h.newCount)} new` : "";
       const self = h.self > 0 ? ` · ${formatCount(h.self)} self` : "";
-      const query = harness === "opencode" ? "1 sqlite query" : `${scanned}${fresh}${self}`;
+      const query = harness === "opencode" || harness === "hermes" ? "1 sqlite query" : `${scanned}${fresh}${self}`;
       activity = theme.paint(fitPlain(query, activityWidth), "dim");
       count = padVis(
         `${theme.paint(formatCount(h.matched), "text", { bold: true })} ${theme.paint("this repo", "faint")}`,