@100xprompt/brain 0.0.0-stage → 0.1.1

package/src/adapters/hermes/records.ts

@@ -0,0 +1,285 @@
+import type { Database } from "bun:sqlite"
+import { randomBytes } from "node:crypto"
+import { join } from "node:path"
+import { exists, versionOf } from "../../fsutil.ts"
+import type { ToolKind, Turn } from "../../session/types.ts"
+import { asText, toolKindOf } from "../../session/util.ts"
+import { asRecord, safeToolName } from "../opencode/tools.ts"
+
+// Hermes Agent (NousResearch/hermes-agent): where its sessions live and what its rows look like, shared by the
+// reader and the writer. The semantics are ported from session-migrate (xhluca/session-migrate, MIT licence,
+// copyright (c) 2026 xhluca): docs/hermes-format.md and src/session_migrate/formats/hermes.py, pinned to Hermes
+// 0.20.6 (schema 26), whose real capture is test/fixtures/native-corpus/hermes. Checked as well against the
+// Hermes 0.18.2 source (hermes_state.py SessionDB, schema 19; agent/chat_completion_helpers.py
+// build_assistant_message; agent/context_compressor.py; cli.py), which keeps the same tables with fewer columns.
+//
+// Every session of every surface (CLI, TUI, gateway, cron) is a row of $HERMES_HOME/state.db (HERMES_HOME
+// defaults to ~/.hermes; like the other adapters, this one reads the default and does not follow the variable).
+// A session's id is the local start time plus six hex digits (YYYYMMDD_HHMMSS_abcdef); its messages are rows in
+// OpenAI chat shape: role user/assistant/tool, an assistant's calls as a JSON `tool_calls` list
+// ({id, call_id, response_item_id, type: "function", function: {name, arguments}}), each result a `tool` row
+// with tool_call_id and tool_name. Hermes replays only rows with active = 1, in id order: rewound turns are
+// active = 0, and turns a compaction replaced are active = 0 with compacted = 1. A compaction summary is a
+// message whose text starts with Hermes's summary prefix (flagged _compressed_summary = 1 since schema 2x).
+// FTS5 tables (messages_fts, messages_fts_trigram) are kept in sync by triggers on messages.
+
+export const TOOL = "hermes"
+export const LABEL = "Hermes Agent"
+
+/** Hermes versions whose store the writer was checked against: the capture's, and the one installed here. */
+export const TESTED_VERSIONS = ["0.18.2", "0.20.6"]
+/** The store schemas those versions keep (schema_version.version): 19 for 0.18.2, 26 for 0.20.6. */
+export const MIN_SCHEMA = 19
+export const MAX_SCHEMA = 26
+
+export const hermesDir = (home: string) => join(home, ".hermes")
+export const storePath = (home: string) => join(hermesDir(home), "state.db")
+
+/** The hermes launcher: the installer's ~/.local/bin/hermes first, else the one on PATH (as PATH is now). */
+export function hermesBin(home: string): { path: string; command: string } | undefined {
+  const onPath = Bun.which("hermes", { PATH: process.env.PATH ?? "" })
+  const own = join(home, ".local", "bin", "hermes")
+  if (exists(own)) return { path: own, command: onPath === own ? "hermes" : own }
+  return onPath ? { path: onPath, command: "hermes" } : undefined
+}
+
+/** "0.18.2" from `hermes --version` ("Hermes Agent v0.18.2 (2026.7.7.2) ..."). */
+export function hermesVersion(bin: string): string | undefined {
+  const line = versionOf(bin)
+  return line?.match(/Hermes Agent v(\d+\.\d+\.\d+)/)?.[1] ?? line?.match(/\b(\d+\.\d+\.\d+)\b/)?.[1]
+}
+
+const pad = (n: number, w = 2) => String(n).padStart(w, "0")
+
+/** A new session id as the CLI makes one: local start time, then six hex digits (cli.py). */
+export function newSessionId(now: Date): string {
+  const hex = randomBytes(3).toString("hex")
+  return `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}_${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}_${hex}`
+}
+
+export const SESSION_ID = /^\d{8}_\d{6}_[0-9a-f]{6,8}$/
+
+/** The columns a table has in this store: the reader and writer work with both schema 19 and 26. */
+export function columnsOf(d: Database, table: string): Set<string> {
+  return new Set((d.query(`PRAGMA table_info("${table}")`).all() as Array<{ name: string }>).map((c) => c.name))
+}
+
+export function schemaVersion(d: Database): number | undefined {
+  try {
+    const v = (d.query("SELECT version FROM schema_version LIMIT 1").get() as { version: unknown } | null)?.version
+    return typeof v === "number" ? v : undefined
+  } catch {
+    return undefined
+  }
+}
+
+// --- Compaction summaries (agent/context_compressor.py) ---
+
+/** The prefix Hermes still recognises from its first summaries; session-migrate writes summaries with it. */
+export const LEGACY_SUMMARY_PREFIX = "[CONTEXT SUMMARY]:"
+/** The current and historical prefixes all open with this, on one line, before the summary on the next. */
+const SUMMARY_PREFIX_START = "[CONTEXT COMPACTION"
+export const SUMMARY_END_MARKER = "--- END OF CONTEXT SUMMARY — respond to the message below, not the summary above ---"
+const MERGED_HEADER = "[PRIOR CONTEXT — for reference only; not a new message]"
+const MERGED_DELIMITER = "[END OF PRIOR CONTEXT — COMPACTION SUMMARY BELOW]"
+
+/**
+ * A compaction summary in a message's text: the summary itself, and the message it was merged into when Hermes
+ * appended it to the first kept message instead of giving it its own (that message's own text comes first).
+ */
+export function summaryOf(text: string, flagged: boolean): { summary: string; prior?: string } | undefined {
+  let body = text.trimStart()
+  let prior: string | undefined
+  const merged = body.indexOf(MERGED_DELIMITER)
+  if (merged >= 0) {
+    prior = body.slice(0, merged).replace(MERGED_HEADER, "").trim()
+    body = body.slice(merged + MERGED_DELIMITER.length).trimStart()
+  }
+  if (body.startsWith(LEGACY_SUMMARY_PREFIX)) body = body.slice(LEGACY_SUMMARY_PREFIX.length)
+  else if (body.startsWith(SUMMARY_PREFIX_START)) body = body.includes("\n") ? body.slice(body.indexOf("\n") + 1) : ""
+  else if (!flagged) return undefined
+  body = body.trim()
+  if (body.endsWith(SUMMARY_END_MARKER)) body = body.slice(0, -SUMMARY_END_MARKER.length).trimEnd()
+  return { summary: body, ...(prior ? { prior } : {}) }
+}
+
+/** A summary as Hermes keeps one: the legacy prefix both 0.18 and 0.20 recognise, and the end marker. */
+export const summaryText = (summary: string) => `${LEGACY_SUMMARY_PREFIX}\n${summary.trim()}\n\n${SUMMARY_END_MARKER}`
+
+// --- Message content ---
+
+/** Structured content (text + image parts) is stored as this prefix and JSON (SessionDB._encode_content). */
+const CONTENT_JSON_PREFIX = "\u0000json:"
+
+export type Part = { type?: unknown; text?: unknown; image_url?: unknown; url?: unknown }
+
+/** A message's content: its text, or its parts when it was stored structured. */
+export function decodeContent(raw: unknown): string | Part[] {
+  if (typeof raw !== "string") return raw === null || raw === undefined ? "" : asText(raw)
+  let json: string | undefined
+  if (raw.startsWith(CONTENT_JSON_PREFIX)) json = raw.slice(CONTENT_JSON_PREFIX.length)
+  else if (raw.trimStart().startsWith("[{")) json = raw
+  if (json === undefined) return raw
+  try {
+    const v = JSON.parse(json)
+    // Only a list of typed parts is structured content; anything else is text that happens to look like JSON.
+    if (Array.isArray(v) && v.length && v.every((p) => p && typeof p === "object" && typeof p.type === "string")) return v as Part[]
+  } catch {}
+  return raw.startsWith(CONTENT_JSON_PREFIX) ? json : raw
+}
+
+export const partsText = (c: string | Part[]) =>
+  typeof c === "string"
+    ? c
+    : c
+        .map((p) => (typeof p.text === "string" ? p.text : ""))
+        .filter(Boolean)
+        .join("\n")
+
+/** An image part's URL (image_url as {url} or as a string; input_image). */
+export function imageUrlOf(p: Part): string | undefined {
+  if (p.type !== "image_url" && p.type !== "input_image") return undefined
+  const v = p.image_url
+  if (v && typeof v === "object" && typeof (v as { url?: unknown }).url === "string") return (v as { url: string }).url
+  if (typeof v === "string") return v
+  return typeof p.url === "string" ? p.url : undefined
+}
+
+// --- Tool results ---
+
+/**
+ * A tool row's text and whether the call worked. Hermes's terminal (and several other tools) answer with a JSON
+ * object: {"output", "exit_code", "error"}; a truthy error or a non-zero exit code is a failure.
+ */
+export function toolOutput(c: string | Part[]): { text: string; ok: boolean } {
+  const text = partsText(c)
+  let v: unknown
+  try {
+    v = JSON.parse(text)
+  } catch {
+    return { text, ok: true }
+  }
+  if (!v || typeof v !== "object" || Array.isArray(v)) return { text, ok: true }
+  const o = v as { output?: unknown; error?: unknown; exit_code?: unknown }
+  const failed = !!o.error || (typeof o.exit_code === "number" && o.exit_code !== 0)
+  if (typeof o.output === "string") return { text: o.output, ok: !failed }
+  if (failed && typeof o.error === "string" && Object.keys(o).every((k) => k === "error" || k === "exit_code" || k === "output")) return { text: o.error, ok: false }
+  return { text, ok: !failed }
+}
+
+/** Whether plain text would read back as one of the JSON results above (it then has to be wrapped). */
+const looksLikeResult = (text: string) => {
+  try {
+    const v = JSON.parse(text)
+    return !!v && typeof v === "object" && !Array.isArray(v) && ("error" in v || "exit_code" in v || "output" in v)
+  } catch {
+    return false
+  }
+}
+
+/**
+ * A result as a tool row's content: the terminal's own JSON for terminal calls, plain text for other
+ * successful calls, and the JSON envelope session-migrate uses when plain text cannot say it (a failure, a NUL).
+ */
+export function toolContent(text: string, ok: boolean, terminal: boolean): string {
+  if (terminal) return pyJson({ output: text, exit_code: ok ? 0 : 1, error: null })
+  if (ok && text && !text.includes("\u0000") && !looksLikeResult(text)) return text
+  return pyJson({ output: text, error: ok ? null : text || true, exit_code: ok ? 0 : 1 })
+}
+
+// --- Tool calls ---
+
+/** What a Hermes tool does: its file tools are read_file, write_file, patch and search_files, its shell terminal. */
+export function hermesToolKind(name: string): ToolKind {
+  if (name === "patch") return "edit"
+  if (name === "web_extract") return "web"
+  if (name === "execute_code") return "shell"
+  if (name === "delegate_task") return "task"
+  return toolKindOf(name)
+}
+
+type Call = Extract<Turn, { kind: "tool_call" }>
+const str = (v: unknown) => (typeof v === "string" && v ? v : undefined)
+const firstOf = (i: Record<string, unknown>, keys: string[]) => keys.map((k) => str(i[k])).find(Boolean)
+const FILE_KEYS = ["path", "file_path", "filePath", "target_file", "absolute_path", "file"]
+
+/** A shell command as one line: Codex passes ["bash", "-lc", "…"]. */
+function commandOf(v: unknown): string | undefined {
+  if (typeof v === "string") return v || undefined
+  if (!Array.isArray(v) || !v.length || !v.every((x) => typeof x === "string")) return undefined
+  const [sh, flag, script] = v as string[]
+  if (v.length === 3 && /^(ba|z)?sh$/.test(sh!.split("/").pop()!) && /^-l?c$/.test(flag!)) return script
+  return v.join(" ")
+}
+
+/**
+ * A call as Hermes's own tools take it (tools/terminal_tool.py, tools/file_tools.py), when its arguments say what
+ * the tool needs; any other call keeps its name (made safe for providers) and its input.
+ */
+export function hermesCall(c: Call): { name: string; args: Record<string, unknown>; mapped: boolean } {
+  const i = asRecord(c.input)
+  const native = ((): { name: string; args: Record<string, unknown> } | undefined => {
+    switch (c.toolKind) {
+      case "shell": {
+        const command = commandOf(i.command ?? i.cmd)
+        if (!command) return undefined
+        const workdir = firstOf(i, ["workdir", "cwd", "working_dir", "workingDirectory"])
+        return { name: "terminal", args: { command, ...(workdir ? { workdir } : {}) } }
+      }
+      case "read": {
+        const path = firstOf(i, FILE_KEYS)
+        if (!path) return undefined
+        const range = Object.fromEntries(["offset", "limit"].filter((k) => typeof i[k] === "number").map((k) => [k, i[k]]))
+        return { name: "read_file", args: { path, ...range } }
+      }
+      case "write": {
+        const path = firstOf(i, FILE_KEYS)
+        const content = [i.content, i.contents, i.file_text].find((v) => typeof v === "string")
+        return path && content !== undefined ? { name: "write_file", args: { path, content } } : undefined
+      }
+      case "edit": {
+        const path = firstOf(i, FILE_KEYS)
+        const before = [i.old_string, i.oldString, i.old_str].find((v) => typeof v === "string")
+        const after = [i.new_string, i.newString, i.new_str].find((v) => typeof v === "string")
+        if (!path || before === undefined || after === undefined) return undefined
+        const all = [i.replace_all, i.replaceAll].find((v) => typeof v === "boolean")
+        return { name: "patch", args: { mode: "replace", path, old_string: before, new_string: after, ...(all !== undefined ? { replace_all: all } : {}) } }
+      }
+      case "search": {
+        const pattern = firstOf(i, ["pattern", "query", "regex", "glob_pattern"])
+        if (!pattern) return undefined
+        const path = firstOf(i, ["path", "dir", "directory", "target_directory"])
+        const files = /glob|find_?files|file_search/i.test(c.name) || i.target === "files"
+        if (!files && !/grep|ripgrep|search_files|grep_search|^rg$/i.test(c.name)) return undefined
+        return { name: "search_files", args: { pattern, target: files ? "files" : "content", ...(path ? { path } : {}) } }
+      }
+      default:
+        return undefined
+    }
+  })()
+  if (native) return { ...native, mapped: native.name !== c.name || pyJson(native.args) !== pyJson(i) }
+  return { name: safeToolName(c.name), args: i, mapped: false }
+}
+
+/** The Responses item id Hermes derives from a call id (codex_responses_adapter._derive_responses_function_call_id). */
+export function responseItemId(callId: string): string {
+  if (callId.startsWith("fc_")) return callId
+  if (callId.startsWith("call_") && callId.length > 5) return `fc_${callId.slice(5)}`
+  const clean = callId.replace(/[^A-Za-z0-9_-]/g, "")
+  return `fc_${clean.slice(0, 48) || "call"}`
+}
+
+/** JSON as Python's json.dumps writes it by default (", " and ": ", non-ASCII escaped), as Hermes stores tool_calls. */
+export function pyJson(v: unknown): string {
+  if (v === null || v === undefined) return "null"
+  if (typeof v === "string") return JSON.stringify(v).replace(/[\u0080-￿]/g, (ch) => `\\u${ch.charCodeAt(0).toString(16).padStart(4, "0")}`)
+  if (typeof v === "number") return Number.isFinite(v) ? String(v) : "null"
+  if (typeof v === "boolean") return v ? "true" : "false"
+  if (Array.isArray(v)) return `[${v.map(pyJson).join(", ")}]`
+  if (typeof v === "object")
+    return `{${Object.entries(v as Record<string, unknown>)
+      .filter(([, x]) => x !== undefined)
+      .map(([k, x]) => `${pyJson(k)}: ${pyJson(x)}`)
+      .join(", ")}}`
+  return pyJson(String(v))
+}