nlm-memory 0.4.0

package/src/core/adapters/hermes.ts

@@ -0,0 +1,277 @@
+/**
+ * Hermes adapter.
+ *
+ * Reads ~/.hermes/sessions/*.json files. Two file shapes coexist:
+ *
+ *   session_<date>_<id>.json     — live session format
+ *     { session_id, model, session_start, last_updated, messages: [...] }
+ *
+ *   request_dump_<date>_<id>_<date>_<time>.json  — error-dump format
+ *     { timestamp, session_id, request: { body: { messages: [...] } } }
+ *
+ * Discovery dedupes by `session_id`: when both shapes exist for the same
+ * session (failure case), the live `session_` file wins because it carries
+ * richer metadata.
+ */
+
+import { promises as fs, existsSync, statSync } from "node:fs";
+import { basename, extname, join } from "node:path";
+import { homedir } from "node:os";
+import type {
+  DetectionResult,
+  DiscoverOptions,
+  SessionChunk,
+  TranscriptAdapter,
+} from "@ports/transcript-adapter.js";
+import {
+  durationMinutes,
+  normalizeTimestamp,
+  safeSessionId,
+} from "./common.js";
+
+const TOOL_RESULT_PREVIEW_CHARS = 200;
+
+export interface HermesAdapterOptions {
+  readonly sessionsPath?: string;
+  readonly idleMinutes?: number;
+}
+
+interface Turn {
+  readonly role: string;
+  readonly text: string;
+  readonly timestamp: string;
+}
+
+export class HermesAdapter implements TranscriptAdapter {
+  readonly name = "hermes";
+  readonly runtimeVersion = "hermes/1.0";
+  readonly transcriptKind = "hermes-json";
+
+  private readonly sessionsPath: string;
+  readonly idleMinutes: number;
+
+  constructor(opts: HermesAdapterOptions = {}) {
+    this.sessionsPath =
+      opts.sessionsPath ?? join(homedir(), ".hermes", "sessions");
+    this.idleMinutes = opts.idleMinutes ?? 30;
+  }
+
+  detect(): DetectionResult {
+    const p = join(homedir(), ".hermes", "sessions");
+    if (existsSync(p) && statSync(p).isDirectory()) {
+      return { adapterName: this.name, enabled: true, path: p, hint: null };
+    }
+    return {
+      adapterName: this.name,
+      enabled: false,
+      path: null,
+      hint: "Hermes not detected — ~/.hermes/sessions/ missing.",
+    };
+  }
+
+  async discover(options: DiscoverOptions = {}): Promise<ReadonlyArray<string>> {
+    if (!existsSync(this.sessionsPath)) return [];
+
+    const allFiles: string[] = [];
+    const entries = await fs.readdir(this.sessionsPath, { withFileTypes: true });
+    for (const ent of entries) {
+      if (!ent.isFile() || extname(ent.name) !== ".json") continue;
+      const full = join(this.sessionsPath, ent.name);
+      const st = await fs.stat(full);
+      if (st.size === 0) continue;
+      allFiles.push(full);
+    }
+
+    // Build session_id → {session, dump} map, preferring session_ files.
+    const bySid = new Map<string, { session?: string; dump?: string }>();
+    for (const jf of allFiles) {
+      let data: Record<string, unknown>;
+      try {
+        const raw = await fs.readFile(jf, "utf8");
+        data = JSON.parse(raw) as Record<string, unknown>;
+      } catch {
+        continue;
+      }
+      const sidVal = data["session_id"];
+      const sid = typeof sidVal === "string" && sidVal ? sidVal : basename(jf, ".json");
+      const hasMessages = "messages" in data && !("request" in data);
+      const slot = hasMessages ? "session" : "dump";
+      const cur = bySid.get(sid) ?? {};
+      cur[slot] = jf;
+      bySid.set(sid, cur);
+    }
+
+    const chosen: { mtime: number; path: string }[] = [];
+    for (const variants of bySid.values()) {
+      const canonical = variants.session ?? variants.dump;
+      if (!canonical) continue;
+      const st = await fs.stat(canonical);
+      if (options.since && st.mtime < options.since) continue;
+      chosen.push({ mtime: st.mtimeMs, path: canonical });
+    }
+    chosen.sort((a, b) => a.mtime - b.mtime);
+    return chosen.map((c) => c.path);
+  }
+
+  async parseSession(path: string): Promise<SessionChunk | null> {
+    let data: Record<string, unknown>;
+    try {
+      const raw = await fs.readFile(path, "utf8");
+      data = JSON.parse(raw) as Record<string, unknown>;
+    } catch {
+      return null;
+    }
+
+    let totalBytes = 0;
+    try {
+      totalBytes = (await fs.stat(path)).size;
+    } catch {
+      return null;
+    }
+
+    let msgs: unknown[];
+    let sessionId: string;
+    let fileStartedAt: string;
+    let fileEndedAt: string;
+
+    if ("messages" in data && !isRecord(data["request"])) {
+      // Live session format
+      msgs = Array.isArray(data["messages"]) ? data["messages"] : [];
+      sessionId =
+        typeof data["session_id"] === "string" && data["session_id"]
+          ? data["session_id"]
+          : basename(path, ".json");
+      fileStartedAt =
+        typeof data["session_start"] === "string" ? data["session_start"] : "";
+      fileEndedAt =
+        typeof data["last_updated"] === "string" ? data["last_updated"] : "";
+    } else {
+      // Request dump format
+      const body = isRecord(data["request"]) && isRecord(data["request"]["body"])
+        ? (data["request"]["body"] as Record<string, unknown>)
+        : {};
+      msgs = Array.isArray(body["messages"]) ? body["messages"] : [];
+      sessionId =
+        typeof data["session_id"] === "string" && data["session_id"]
+          ? data["session_id"]
+          : basename(path, ".json");
+      const ts = typeof data["timestamp"] === "string" ? data["timestamp"] : "";
+      fileStartedAt = ts;
+      fileEndedAt = ts;
+    }
+
+    if (msgs.length === 0) return null;
+
+    fileStartedAt = normalizeTimestamp(fileStartedAt);
+    fileEndedAt = normalizeTimestamp(fileEndedAt);
+
+    const turns: Turn[] = [];
+    let firstTs = "";
+    let lastTs = "";
+
+    for (const m of msgs) {
+      if (!isRecord(m)) continue;
+      const role = typeof m["role"] === "string" ? m["role"] : "";
+      if (!role || role === "system") continue;
+
+      const toolCalls = Array.isArray(m["tool_calls"])
+        ? (m["tool_calls"] as unknown[])
+        : null;
+      const text = extractHermesText(m["content"], toolCalls);
+      if (!text.trim()) continue;
+
+      const msgTs = normalizeTimestamp(m["timestamp"]);
+      if (msgTs) {
+        if (!firstTs) firstTs = msgTs;
+        lastTs = msgTs;
+      }
+
+      turns.push({ role, text, timestamp: msgTs });
+    }
+
+    if (turns.length === 0) return null;
+
+    if (!firstTs && fileStartedAt) firstTs = fileStartedAt;
+    if (!lastTs && fileEndedAt) lastTs = fileEndedAt;
+
+    const transcript = turns.map((t) => `[${t.role}] ${t.text}`).join("\n\n");
+    const duration = durationMinutes(firstTs, lastTs);
+    const label = provisionalLabel(turns);
+
+    return {
+      id: safeSessionId("hm", sessionId),
+      runtime: this.runtimeVersion,
+      runtimeSessionId: sessionId,
+      sourcePath: path,
+      startedAt: firstTs,
+      endedAt: lastTs,
+      durationMin: duration,
+      turnCount: turns.length,
+      byteRange: [0, totalBytes],
+      projectDir: "",
+      gitBranch: "",
+      text: transcript,
+      label,
+    };
+  }
+}
+
+// ── helpers ──────────────────────────────────────────────────────────────
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return !!v && typeof v === "object" && !Array.isArray(v);
+}
+
+function extractHermesText(
+  content: unknown,
+  toolCalls: ReadonlyArray<unknown> | null,
+): string {
+  const parts: string[] = [];
+
+  if (typeof content === "string") {
+    const t = content.trim();
+    if (t) parts.push(t);
+  } else if (Array.isArray(content)) {
+    for (const block of content) {
+      if (!isRecord(block)) continue;
+      const btype = block["type"];
+      if (btype === "text") {
+        const txt = block["text"];
+        if (typeof txt === "string" && txt.trim()) parts.push(txt.trim());
+      } else if (btype === "tool_result") {
+        let res = block["content"];
+        if (Array.isArray(res)) {
+          res = res
+            .filter(isRecord)
+            .map((b) => (typeof b["text"] === "string" ? (b["text"] as string) : ""))
+            .join("\n");
+        }
+        if (typeof res === "string" && res) {
+          const preview = res.slice(0, TOOL_RESULT_PREVIEW_CHARS);
+          const ellipsis = res.length > TOOL_RESULT_PREVIEW_CHARS ? "…" : "";
+          parts.push(`[tool_result: ${preview}${ellipsis}]`);
+        }
+      }
+    }
+  }
+
+  if (toolCalls) {
+    for (const tc of toolCalls) {
+      if (!isRecord(tc)) continue;
+      const fn = isRecord(tc["function"]) ? (tc["function"] as Record<string, unknown>) : {};
+      const name = typeof fn["name"] === "string" ? fn["name"] : "tool";
+      parts.push(`[tool_use: ${name}]`);
+    }
+  }
+
+  return parts.filter((p) => p).join("\n");
+}
+
+function provisionalLabel(turns: ReadonlyArray<Turn>): string {
+  for (const t of turns) {
+    if (t.role !== "user") continue;
+    const firstLine = t.text.split("\n", 1)[0]?.trim();
+    if (firstLine) return firstLine.slice(0, 80);
+  }
+  return "Untitled session";
+}

package/src/core/adapters/jsonl-generic.ts

@@ -0,0 +1,208 @@
+/**
+ * Generic JSONL adapter — driven by per-source `parseConfig`.
+ *
+ * Reads any directory of newline-delimited JSON files where each line is one
+ * conversation turn. The three baked-in adapters (claude-code, hermes, pi)
+ * stay as their own classes because each has format-specific quirks that
+ * would bloat a generic config schema. This adapter exists for everything
+ * else: Cursor, Codex, custom logs, anything a user can drop on disk in a
+ * consistent shape.
+ *
+ * parseConfig shape (all optional except where noted):
+ *   {
+ *     "textField":         "content",     // required — the message body
+ *     "roleField":         "role",        // optional — "user"/"assistant" filter
+ *     "userRole":          "user",        // string the user role takes
+ *     "assistantRole":     "assistant",   // string the assistant role takes
+ *     "timestampField":    "timestamp",   // optional — ISO or unix
+ *     "sessionIdField":    "session_id",  // optional — falls back to filename
+ *     "labelField":        "title",       // optional — falls back to filename
+ *     "filePattern":       "*.jsonl",     // glob within pathOrUrl
+ *     "idleMinutes":       15
+ *   }
+ */
+
+import { promises as fs, existsSync, statSync } from "node:fs";
+import { basename, extname, join } from "node:path";
+import type {
+  DetectionResult,
+  DiscoverOptions,
+  SessionChunk,
+  TranscriptAdapter,
+} from "@ports/transcript-adapter.js";
+import { durationMinutes, normalizeTimestamp, safeSessionId } from "./common.js";
+
+export interface JsonlGenericConfig {
+  readonly textField?: string;
+  readonly roleField?: string;
+  readonly userRole?: string;
+  readonly assistantRole?: string;
+  readonly timestampField?: string;
+  readonly sessionIdField?: string;
+  readonly labelField?: string;
+  readonly filePattern?: string;
+  readonly idleMinutes?: number;
+}
+
+export interface JsonlGenericAdapterOptions {
+  readonly name: string;
+  readonly path: string;
+  readonly runtime: string;
+  readonly config: JsonlGenericConfig;
+}
+
+export class JsonlGenericAdapter implements TranscriptAdapter {
+  readonly name: string;
+  readonly runtimeVersion: string;
+  readonly transcriptKind = "jsonl-generic";
+  readonly idleMinutes: number;
+
+  private readonly path: string;
+  private readonly cfg: Required<Omit<JsonlGenericConfig, "idleMinutes">>;
+
+  constructor(opts: JsonlGenericAdapterOptions) {
+    this.name = opts.name;
+    this.runtimeVersion = opts.runtime;
+    this.path = opts.path;
+    this.idleMinutes = opts.config.idleMinutes ?? 15;
+    this.cfg = {
+      textField:      opts.config.textField      ?? "content",
+      roleField:      opts.config.roleField      ?? "role",
+      userRole:       opts.config.userRole       ?? "user",
+      assistantRole:  opts.config.assistantRole  ?? "assistant",
+      timestampField: opts.config.timestampField ?? "timestamp",
+      sessionIdField: opts.config.sessionIdField ?? "session_id",
+      labelField:     opts.config.labelField     ?? "title",
+      filePattern:    opts.config.filePattern    ?? "*.jsonl",
+    };
+  }
+
+  detect(): DetectionResult {
+    if (existsSync(this.path) && statSync(this.path).isDirectory()) {
+      return { adapterName: this.name, enabled: true, path: this.path, hint: null };
+    }
+    return {
+      adapterName: this.name,
+      enabled: false,
+      path: null,
+      hint: `${this.name}: directory not found at ${this.path}`,
+    };
+  }
+
+  async discover(options: DiscoverOptions = {}): Promise<ReadonlyArray<string>> {
+    if (!existsSync(this.path)) return [];
+    const entries = await fs.readdir(this.path, { withFileTypes: true });
+    const wantExt = this.extOfPattern(this.cfg.filePattern);
+    const out: string[] = [];
+    for (const e of entries) {
+      if (!e.isFile()) continue;
+      if (wantExt && extname(e.name) !== wantExt) continue;
+      const full = join(this.path, e.name);
+      if (options.since) {
+        const st = statSync(full);
+        if (st.mtime < options.since) continue;
+      }
+      out.push(full);
+    }
+    return out;
+  }
+
+  async parseSession(filePath: string): Promise<SessionChunk | null> {
+    let raw: string;
+    try {
+      raw = await fs.readFile(filePath, "utf8");
+    } catch {
+      return null;
+    }
+    const lines = raw.split("\n").filter((l) => l.trim().length > 0);
+    if (lines.length === 0) return null;
+
+    const turns: { role: "user" | "assistant"; text: string; timestamp: string }[] = [];
+    let sessionIdFromRows: string | null = null;
+    let labelFromRows: string | null = null;
+
+    for (const line of lines) {
+      let row: Record<string, unknown>;
+      try {
+        row = JSON.parse(line) as Record<string, unknown>;
+      } catch {
+        continue;
+      }
+      if (!sessionIdFromRows && typeof row[this.cfg.sessionIdField] === "string") {
+        sessionIdFromRows = row[this.cfg.sessionIdField] as string;
+      }
+      if (!labelFromRows && typeof row[this.cfg.labelField] === "string") {
+        labelFromRows = row[this.cfg.labelField] as string;
+      }
+      const role = this.classifyRole(row[this.cfg.roleField]);
+      if (!role) continue;
+      const text = this.extractText(row[this.cfg.textField]);
+      if (!text) continue;
+      turns.push({
+        role,
+        text,
+        timestamp: normalizeTimestamp(row[this.cfg.timestampField]),
+      });
+    }
+
+    if (turns.length === 0) return null;
+
+    const startedAt = turns[0]?.timestamp ?? "";
+    const endedAt = turns[turns.length - 1]?.timestamp ?? startedAt;
+    const fileName = basename(filePath, extname(filePath));
+    const rawId = sessionIdFromRows ?? fileName;
+    const label = labelFromRows ?? fileName;
+    const text = turns
+      .map((t) => `${t.role === "user" ? "User" : "Assistant"}: ${t.text}`)
+      .join("\n\n");
+
+    return {
+      id: safeSessionId(this.name, rawId),
+      runtime: this.runtimeVersion,
+      runtimeSessionId: rawId,
+      sourcePath: filePath,
+      startedAt,
+      endedAt,
+      durationMin: durationMinutes(startedAt, endedAt),
+      turnCount: turns.length,
+      byteRange: [0, Buffer.byteLength(raw)],
+      projectDir: this.path,
+      gitBranch: "",
+      text,
+      label,
+    };
+  }
+
+  private classifyRole(raw: unknown): "user" | "assistant" | null {
+    if (raw === undefined || raw === null) {
+      // Some formats omit the field — assume alternating; bias to assistant.
+      return "assistant";
+    }
+    if (typeof raw !== "string") return null;
+    if (raw === this.cfg.userRole) return "user";
+    if (raw === this.cfg.assistantRole) return "assistant";
+    return null;
+  }
+
+  private extractText(raw: unknown): string {
+    if (typeof raw === "string") return raw.trim();
+    if (Array.isArray(raw)) {
+      // OpenAI-style content: [{ type: "text", text: "..." }, ...]
+      const parts: string[] = [];
+      for (const item of raw) {
+        if (typeof item === "string") parts.push(item);
+        else if (item && typeof item === "object" && typeof (item as { text?: string }).text === "string") {
+          parts.push((item as { text: string }).text);
+        }
+      }
+      return parts.join(" ").trim();
+    }
+    return "";
+  }
+
+  private extOfPattern(pattern: string): string | null {
+    const idx = pattern.lastIndexOf(".");
+    if (idx < 0) return null;
+    return pattern.slice(idx);
+  }
+}