@100xprompt/brain 0.0.0-stage → 0.1.1

package/src/adapters/grok-cli/writer.ts

@@ -0,0 +1,329 @@
+import { mkdirSync, rmSync, writeFileSync } from "node:fs"
+import { join, resolve } from "node:path"
+import { toolLabel } from "../../brief.ts"
+import { exists, gitInfo, isDir } from "../../fsutil.ts"
+import { imageDataUrl, parseDataUrl } from "../../session/attachments.ts"
+import type { Project, Session, Turn } from "../../session/types.ts"
+import { countTurns, firstUserText, unpaired } from "../../session/util.ts"
+import type { Readiness, WriteOptions, WriteResult, Writer } from "../types.ts"
+import { grokRejects } from "./image.ts"
+import { grokReader } from "./reader.ts"
+import {
+  LABEL, MAX_FOLDER_NAME, SUMMARY_PREFIX, SYNTHETIC, TESTED_VERSIONS, TOOL,
+  asGrokCall, continuedNote, defaultModel, encodeCwd, grokHome, grokVersion, reminder, sessionsDir,
+} from "./records.ts"
+
+// Continues a portable session in the Grok CLI as a new session folder with the three files Grok's own
+// sessions need: summary.json (the session list), updates.jsonl (what the screen replays) and
+// chat_history.jsonl (what the model is given). Both logs are written because Grok reads them for
+// different things: a session with only updates.jsonl resumes with the earlier turns on screen and an
+// empty model context; one with only chat_history.jsonl is "not found".
+//
+// Tool calls stay structural in both logs: assistant tool_calls paired with tool_result messages for the
+// model, tool_call / tool_call_update events for the screen, mapped to Grok's own tools where the
+// arguments map (asGrokCall), with ids in Grok's call-<uuid>-<n> style. The note saying where the session
+// came from is a synthetic system reminder, the way Grok marks context it adds itself, and it is not on
+// screen. No system message is written: Grok puts its current system prompt in on load (checked: a
+// stored one, short or long, does not change the context it builds, and none is inserted when missing).
+//
+// A compaction follows Grok's own: the screen log keeps every turn, the model's history starts from the
+// summary. Readable reasoning is shown on screen but not given to the model, which only replays its own
+// encrypted reasoning items.
+
+type Row = Record<string, unknown>
+type Call = Extract<Turn, { kind: "tool_call" }>
+type Result = Extract<Turn, { kind: "tool_result" }>
+
+/** Grok's timestamps: RFC 3339 with microseconds. */
+const micros = (ms: number) => new Date(ms).toISOString().replace(/\.(\d{3})Z$/, ".$1000Z")
+
+const shellQuote = (s: string) => (/^[\w./@%+=:,-]+$/.test(s) ? s : `'${s.replace(/'/g, `'\\''`)}'`)
+
+/** Function names the chat completions API accepts. */
+const fnName = (name: string) => name.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 64) || "tool"
+
+/** Arguments must be a JSON object; a freeform input (an apply_patch) is wrapped. */
+const asObject = (input: unknown): Record<string, unknown> =>
+  input && typeof input === "object" && !Array.isArray(input) ? (input as Record<string, unknown>) : { input: input ?? null }
+
+export interface GrokPlan {
+  summary: Row
+  updates: Row[]
+  chat: Row[]
+  lost: string[]
+  expect: { users: number; assistants: number; calls: number }
+}
+
+/** The three files of a new Grok session `id` continuing `session`. Pure: writes nothing. */
+export function planGrokSession(
+  session: Session,
+  opts: { id: string; now: Date; cwd: string; home: string; model: string; git?: Omit<Project, "cwd"> },
+): GrokPlan {
+  const drops = new Map<string, number>()
+  const drop = (what: string, n = 1) => drops.set(what, (drops.get(what) ?? 0) + n)
+  const label = toolLabel(session.header.tool)
+  const { id } = opts
+  const turns = session.turns
+  const lastCompaction = turns.map((t) => t.kind).lastIndexOf("compaction")
+
+  const results = new Map<string, Result>()
+  const callIds = new Set<string>()
+  for (const t of turns) {
+    if (t.kind === "tool_result" && !results.has(t.callId)) results.set(t.callId, t)
+    if (t.kind === "tool_call") callIds.add(t.id)
+  }
+
+  // Grok's call ids: call-<uuid>-<n>, numbered through the session.
+  const callUuid = crypto.randomUUID()
+  const ids = new Map<string, string>()
+  const grokId = (callId: string) => {
+    let v = ids.get(callId)
+    if (!v) ids.set(callId, (v = `call-${callUuid}-${ids.size}`))
+    return v
+  }
+
+  // Event times never go backwards; a turn without a time takes the one before it plus a millisecond.
+  const known = turns.map((t) => (t.at ? Date.parse(t.at) : Number.NaN)).find(Number.isFinite)
+  let clock = (known ?? opts.now.getTime()) - 1
+  const stamp = (at?: string) => {
+    const t = at ? Date.parse(at) : Number.NaN
+    clock = Number.isFinite(t) && t > clock ? t : clock + 1
+    return clock
+  }
+
+  const updates: Row[] = []
+  let events = 0
+  let promptId: string | undefined
+  const event = (update: Row, at?: string) => {
+    const ms = stamp(at)
+    events++
+    updates.push({
+      method: "session/update",
+      params: { sessionId: id, update, _meta: { agentTimestampMs: ms, eventId: `${id}-${events}`, ...(promptId ? { promptId } : {}) } },
+      timestamp: Math.floor(ms / 1000),
+    })
+  }
+  const endPrompt = () => {
+    if (promptId) event({ sessionUpdate: "turn_completed", prompt_id: promptId, stop_reason: "end_turn" })
+    promptId = undefined
+  }
+
+  const chat: Row[] = [
+    { type: "user", content: [{ type: "text", text: reminder(continuedNote(label, session.header.id, opts.now.toISOString().slice(0, 10))) }], [SYNTHETIC]: "system_reminder" },
+  ]
+  const expect = { users: 0, assistants: 0, calls: 0 }
+  let promptIndex = 0
+  let model = session.header.models[session.header.models.length - 1] ?? opts.model
+
+  // The model's side: an assistant message gathers text and calls until a result comes back.
+  let cur: { text: string; model: string; calls: Call[] } | undefined
+  const flush = () => {
+    if (!cur) return
+    const m = cur
+    cur = undefined
+    if (!m.text.trim() && !m.calls.length) return
+    chat.push({
+      type: "assistant",
+      content: m.text,
+      model_id: m.model,
+      ...(m.calls.length ? { tool_calls: m.calls.map((c) => ({ id: grokId(c.id), name: fnName(asGrokCall(c.toolKind, c.name, c.input).name), arguments: JSON.stringify(asObject(asGrokCall(c.toolKind, c.name, c.input).input)) })) } : {}),
+    })
+    if (m.text.trim()) expect.assistants++
+    for (const c of m.calls) {
+      const r = results.get(c.id)
+      if (!r) drop("tool calls without a result (closed as failed)")
+      chat.push({ type: "tool_result", tool_call_id: grokId(c.id), content: r ? r.output + (r.fullPath ? `\n\n[Full output: ${r.fullPath}]` : "") : "No result was recorded for this call." })
+    }
+  }
+
+  // The screen's side, event by event; calls whose result never comes are closed as failed.
+  const screenCall = (c: Call) => {
+    const g = asGrokCall(c.toolKind, c.name, c.input)
+    event(
+      {
+        sessionUpdate: "tool_call",
+        toolCallId: grokId(c.id),
+        title: g.tool?.label ?? c.name,
+        kind: g.tool?.acp ?? "other",
+        status: "pending",
+        rawInput: asObject(g.input),
+        _meta: { "x.ai/tool": { name: g.name, kind: g.tool?.kind ?? "other", label: g.tool?.label ?? c.name, namespace: g.tool?.namespace ?? "external", read_only: g.tool?.readOnly ?? false, version: 1 } },
+      },
+      c.at,
+    )
+    if (!results.has(c.id)) screenResult(c.id, false, "No result was recorded for this call.", c.at)
+  }
+  const screenResult = (callId: string, ok: boolean, output: string, at?: string) =>
+    event({ sessionUpdate: "tool_call_update", toolCallId: grokId(callId), status: ok ? "completed" : "failed", content: [{ type: "content", content: { type: "text", text: output } }] }, at)
+
+  const seen = new Set<string>()
+  const answered = new Set<string>()
+  for (const [i, t] of turns.entries()) {
+    const toModel = i > lastCompaction
+    switch (t.kind) {
+      case "user": {
+        // Grok stores a pasted image in the user message as a content block {type:"image", url:<data URL>} (found by sending one with --prompt-json).
+        const images: Row[] = []
+        for (const a of t.attachments ?? []) {
+          const url = imageDataUrl(a)
+          const bytes = url && toModel ? Buffer.from(parseDataUrl(url)?.base64 ?? "", "base64") : undefined
+          // An image Grok would reject on load makes it move the whole history aside, so it stays behind.
+          if (url && bytes && !grokRejects(bytes)) images.push({ type: "image", url })
+          else drop(url && bytes && toModel ? "attachments Grok would reject (too small or unreadable)" : "attachments", 1)
+        }
+        if (!t.text.trim()) {
+          if (images.length) drop("attachments without text", images.length)
+          break
+        }
+        endPrompt()
+        promptId = crypto.randomUUID()
+        event({ sessionUpdate: "user_message_chunk", content: { type: "text", text: t.text }, _meta: { modelId: opts.model, promptIndex } }, t.at)
+        if (toModel) {
+          flush()
+          chat.push({ type: "user", content: [{ type: "text", text: t.text }, ...images], prompt_index: promptIndex })
+        }
+        promptIndex++
+        // The read-back reads the model's history, which starts at the last compaction.
+        if (toModel) expect.users++
+        break
+      }
+      case "assistant": {
+        if (t.model) model = t.model
+        if (!t.text.trim()) break
+        event({ sessionUpdate: "agent_message_chunk", content: { type: "text", text: t.text } }, t.at)
+        if (!toModel) break
+        // Text after a call is a new response: it was written after the call's result came back.
+        if (cur?.calls.length) flush()
+        cur ??= { text: "", model, calls: [] }
+        cur.text = cur.text ? `${cur.text}\n\n${t.text}` : t.text
+        break
+      }
+      case "tool_call": {
+        if (seen.has(t.id)) {
+          drop("repeated tool call ids")
+          break
+        }
+        seen.add(t.id)
+        screenCall(t)
+        if (toModel) {
+          cur ??= { text: "", model, calls: [] }
+          cur.calls.push(t)
+          expect.calls++
+        }
+        break
+      }
+      case "tool_result": {
+        if (!callIds.has(t.callId)) {
+          drop("tool results without a call")
+          break
+        }
+        if (answered.has(t.callId)) break
+        answered.add(t.callId)
+        screenResult(t.callId, t.ok, t.output, t.at)
+        // A result closes the response it answers, so a call made after it starts a new one.
+        if (toModel && cur?.calls.some((c) => c.id === t.callId)) flush()
+        break
+      }
+      case "reasoning":
+        event({ sessionUpdate: "agent_thought_chunk", content: { type: "text", text: t.text } }, t.at)
+        drop("reasoning (shown on screen, not given to the model)")
+        break
+      case "compaction":
+        if (i === lastCompaction)
+          chat.push({ type: "user", content: [{ type: "text", text: reminder(`${SUMMARY_PREFIX} in ${label}, which replaced the turns before it]\n\n${t.summary}`) }], [SYNTHETIC]: "system_reminder" })
+        break
+      case "file_edit":
+        if (!t.callId || !callIds.has(t.callId)) drop("file edits outside a tool call")
+        break
+      case "subagent":
+        drop("subagent sessions")
+        break
+    }
+  }
+  flush()
+  endPrompt()
+  if (!promptIndex && !updates.length) throw new Error("nothing Grok can show: the session has no messages or tool calls")
+
+  const title = session.header.title ?? firstUserText(session)?.replace(/\s+/g, " ").trim().slice(0, 60) ?? "Session"
+  const started = turns.map((t) => (t.at ? Date.parse(t.at) : Number.NaN)).find(Number.isFinite) ?? opts.now.getTime()
+  const git = opts.git ?? {}
+  const summary: Row = {
+    info: { id, cwd: opts.cwd },
+    session_summary: `${title} (from ${label})`,
+    generated_title: `${title} (from ${label})`,
+    created_at: micros(started),
+    updated_at: micros(opts.now.getTime()),
+    last_active_at: micros(opts.now.getTime()),
+    num_messages: updates.length,
+    num_chat_messages: chat.length,
+    current_model_id: opts.model,
+    next_trace_turn: 0,
+    chat_format_version: 1,
+    grok_home: grokHome(opts.home),
+    sandbox_profile: "off",
+    ...(git.gitRemote ? { git_remotes: [git.gitRemote] } : {}),
+    ...(git.gitBranch ? { head_branch: git.gitBranch } : {}),
+    ...(git.gitCommit ? { head_commit: git.gitCommit } : {}),
+  }
+  const lost = [...drops].map(([what, n]) => `${what} (${n})`)
+  if (lastCompaction >= 0) lost.push("turns before the last compaction are on screen only; the model starts from its summary")
+  return { summary, updates, chat, lost, expect }
+}
+
+const jsonl = (rows: Row[]) => `${rows.map((r) => JSON.stringify(r)).join("\n")}\n`
+
+/** The Grok writer; `version` is for tests, which must not depend on the installed binary. */
+export function grokWriter(opts: { version?: string } = {}): Writer {
+  const installed = (home: string) => opts.version ?? grokVersion(home)
+  return {
+    tool: TOOL,
+    label: LABEL,
+    way: "native",
+
+    async ready(w: WriteOptions): Promise<Readiness> {
+      const v = installed(w.home)
+      if (!v) return { ok: false, why: "the Grok CLI is not installed (`grok --version` did not run)" }
+      if (!TESTED_VERSIONS.includes(v)) return { ok: false, why: `Grok ${v} is not a version this writer was checked against (${TESTED_VERSIONS.join(", ")})` }
+      if (!isDir(w.cwd)) return { ok: false, why: `${w.cwd} is not a folder; Grok lists sessions by the folder they belong to` }
+      if (Buffer.byteLength(encodeCwd(resolve(w.cwd))) > MAX_FOLDER_NAME) return { ok: false, why: "the folder path is too long: Grok names such folders with a hash this writer does not reproduce" }
+      return { ok: true }
+    },
+
+    async write(session: Session, w: WriteOptions): Promise<WriteResult> {
+      const cwd = resolve(w.cwd)
+      let id = Bun.randomUUIDv7()
+      const group = join(sessionsDir(w.home), encodeCwd(cwd))
+      while (exists(join(group, id))) id = Bun.randomUUIDv7()
+      const dir = join(group, id)
+      const plan = planGrokSession(session, { id, now: new Date(), cwd, home: w.home, model: defaultModel(w.home), git: gitInfo(cwd, w.home) })
+      const files = { "summary.json": `${JSON.stringify(plan.summary, null, 2)}\n`, "updates.jsonl": jsonl(plan.updates), "chat_history.jsonl": jsonl(plan.chat) }
+      if (!w.dryRun) {
+        mkdirSync(group, { recursive: true })
+        // A new folder only: an existing session is never touched.
+        mkdirSync(dir)
+        try {
+          for (const [name, text] of Object.entries(files)) writeFileSync(join(dir, name), text, { flag: "wx" })
+          const back = await grokReader.read({ tool: TOOL, sourceId: id, path: dir }, w.home)
+          const n = countTurns(back)
+          const pairs = unpaired(back)
+          if (n.user !== plan.expect.users || n.tool_call !== plan.expect.calls || pairs.calls.length || pairs.results.length)
+            throw new Error(`the new Grok session did not read back intact (users ${n.user}/${plan.expect.users}, tool calls ${n.tool_call}/${plan.expect.calls}, unpaired ${pairs.calls.length + pairs.results.length})`)
+        } catch (e) {
+          rmSync(dir, { recursive: true, force: true })
+          throw new Error(`${(e as Error).message}; nothing was kept`)
+        }
+      }
+      return {
+        tool: TOOL,
+        way: "native",
+        sessionId: id,
+        written: Object.keys(files).map((f) => join(dir, f)),
+        open: `cd ${shellQuote(cwd)} && grok --resume ${id}`,
+        lost: plan.lost,
+        dryRun: !!w.dryRun,
+      }
+    },
+  }
+}
+
+export const grokNativeWriter = grokWriter()

package/src/adapters/hermes/index.ts

@@ -0,0 +1,8 @@
+import type { Reader, Writer } from "../types.ts"
+import { hermesReader } from "./reader.ts"
+import { hermesNativeWriter } from "./writer.ts"
+
+// Hermes Agent (Nous Research): reads the sessions in ~/.hermes/state.db, and continues any session as a new
+// native session in that store (backed up first; refused while Hermes holds it locked).
+export const readers: Reader[] = [hermesReader]
+export const writers: Writer[] = [hermesNativeWriter]

package/src/adapters/hermes/reader.ts

@@ -0,0 +1,249 @@
+import type { Database } from "bun:sqlite"
+import { exists, gitInfo } from "../../fsutil.ts"
+import { keepImage, parseDataUrl } from "../../session/attachments.ts"
+import type { Attachment, Session, SessionHeader, Turn } from "../../session/types.ts"
+import { clip, header, iso, lossCounter, noteModel } from "../../session/util.ts"
+import { withSnapshot } from "../../sqlite.ts"
+import { CONTINUED_NOTE } from "../opencode/note.ts"
+import type { Reader, SessionRef } from "../types.ts"
+import { LABEL, TOOL, columnsOf, decodeContent, hermesToolKind, imageUrlOf, partsText, storePath, summaryOf, toolOutput, type Part } from "./records.ts"
+
+// Reads Hermes Agent sessions from ~/.hermes/state.db (records.ts), always from a copy with its write-ahead log,
+// as Hermes keeps the store open in WAL mode. Columns are looked up per store, so the schema-19 store of 0.18.2
+// and the schema-26 store of 0.20.6 read alike. Only Hermes's active replay context becomes turns, as
+// session-migrate projects it: rewound rows and rows a compaction replaced are counted in `lost`, never replayed.
+//
+// The list shows what Hermes's own session picker shows: no delegate (subagent) runs, no archived or hidden
+// sessions, and for a session that was compressed into a continuation only the continuation, which starts with
+// the summary and names the session it continues as its parent.
+
+type Row = Record<string, any>
+
+const json = (v: unknown): any => {
+  if (typeof v !== "string" || !v) return undefined
+  try {
+    return JSON.parse(v)
+  } catch {
+    return undefined
+  }
+}
+const text = (v: unknown) => (typeof v === "string" && v ? v : undefined)
+const on = (v: unknown) => v === 1 || v === "1" || v === true
+
+/** The newest moment a session row or its messages record. */
+const latest = (...vs: unknown[]) => {
+  const ts = vs.map((v) => (typeof v === "number" && Number.isFinite(v) ? v : 0))
+  return iso(Math.max(...ts))
+}
+
+export function listHermes(d: Database, path: string): SessionRef[] {
+  const cols = columnsOf(d, "sessions")
+  const pick = (c: string) => (cols.has(c) ? `s.${c}` : "NULL")
+  const rows = d
+    .query(
+      `SELECT s.id, s.title, s.cwd, s.started_at, s.ended_at, s.end_reason, s.source, s.model_config,
+              ${pick("archived")} AS archived, ${pick("hidden")} AS hidden, ${pick("last_activity_at")} AS last_activity_at,
+              (SELECT MAX(m.timestamp) FROM messages m WHERE m.session_id = s.id) AS last,
+              EXISTS (SELECT 1 FROM messages m WHERE m.session_id = s.id AND COALESCE(m.active, 1) = 1) AS live,
+              EXISTS (SELECT 1 FROM sessions c WHERE c.parent_session_id = s.id) AS has_child
+       FROM sessions s`,
+    )
+    .all() as Row[]
+  const refs: SessionRef[] = []
+  for (const r of rows) {
+    if (!on(r.live) || on(r.archived) || on(r.hidden) || r.source === "tool") continue
+    if (json(r.model_config)?._delegate_from) continue
+    // Compressed into a continuation: the continuation is the live conversation (resolve_resume_session_id).
+    if (r.end_reason === "compression" && on(r.has_child)) continue
+    const updatedAt = latest(r.last, r.ended_at, r.last_activity_at, r.started_at)
+    refs.push({
+      tool: TOOL,
+      sourceId: String(r.id),
+      path,
+      ...(text(r.title) ? { title: String(r.title) } : {}),
+      ...(text(r.cwd) ? { cwd: String(r.cwd) } : {}),
+      ...(updatedAt ? { updatedAt } : {}),
+    })
+  }
+  return refs
+}
+
+/** What kind of child a session is of its parent: a /branch, a delegate run, or a compression continuation. */
+function parentOf(d: Database, s: Row): SessionHeader["parent"] {
+  if (!s.parent_session_id) return undefined
+  const id = `${TOOL}:${s.parent_session_id}`
+  const config = json(s.model_config) ?? {}
+  if (config._delegate_from) return { id, kind: "subagent" }
+  if (config._branched_from) return { id, kind: "fork" }
+  const p = d.query("SELECT end_reason FROM sessions WHERE id = ?").get(s.parent_session_id) as { end_reason?: unknown } | null
+  return { id, kind: p?.end_reason === "branched" ? "fork" : "continued" }
+}
+
+/** A tool call's arguments: JSON text as Hermes stores it, parsed when it is JSON. */
+function argsOf(v: unknown): unknown {
+  if (v && typeof v === "object") return v
+  if (typeof v !== "string") return {}
+  try {
+    return JSON.parse(v)
+  } catch {
+    return { input: v }
+  }
+}
+
+/** Whether OpenRouter-style reasoning_details carry a signature or encrypted data that cannot cross tools. */
+const signedDetails = (v: unknown) =>
+  Array.isArray(v) && v.some((x) => x && typeof x === "object" && (x.signature || x.data || x.encrypted_content || String(x.type ?? "").includes("encrypted")))
+
+/** One session from an open Hermes store. */
+export function readHermes(d: Database, id: string, where: { path: string; home: string }): Session {
+  const s = d.query("SELECT * FROM sessions WHERE id = ?").get(id) as Row | null
+  if (!s) throw new Error(`no Hermes session ${id} in ${where.path}`)
+  const cwd = text(s.cwd)
+  const branch = text(s.git_branch)
+  const h = header(TOOL, id, {
+    sourcePath: where.path,
+    ...(text(s.title) ? { title: String(s.title) } : {}),
+    project: { ...(cwd ? { cwd, ...gitInfo(cwd, where.home) } : {}), ...(branch ? { gitBranch: branch } : {}) },
+    ...(iso(s.started_at) ? { startedAt: iso(s.started_at)! } : {}),
+  })
+  noteModel(h, text(s.model))
+  // Models the session's API calls used (schema 2x keeps a usage row per model).
+  if (columnsOf(d, "session_model_usage").size)
+    for (const u of d.query("SELECT model FROM session_model_usage WHERE session_id = ? ORDER BY first_seen").all(id) as Row[]) noteModel(h, text(u.model))
+  const parent = parentOf(d, s)
+  if (parent) h.parent = parent
+
+  const lost = lossCounter()
+  const turns: Turn[] = []
+  const emitted = new Set<string>()
+  /** Calls still waiting for their result, by the id Hermes stored (duplicates queue up). */
+  const waiting = new Map<string, string[]>()
+  let last = 0
+  /** Whether a prompt was read yet: brain's note opens the first one. */
+  let prompted = false
+
+  for (const r of d.query("SELECT * FROM messages WHERE session_id = ? ORDER BY id").all(id) as Row[]) {
+    if (typeof r.timestamp === "number" && r.timestamp > last) last = r.timestamp
+    // Hermes heals a NULL active to 1 on startup; only 0 is out of the replay.
+    if (r.active !== null && r.active !== undefined && !on(r.active)) {
+      lost.add(on(r.compacted) ? "turns Hermes compacted away (still in its store)" : "rewound turns")
+      continue
+    }
+    const role = String(r.role ?? "")
+    if (role === "session_meta") continue
+    if (on(r.observed)) {
+      lost.add("group-chat messages Hermes only observed")
+      continue
+    }
+    const at = iso(r.timestamp)
+    const stamp = at ? { at } : {}
+    const content = decodeContent(r.content)
+    let body = partsText(content)
+
+    if (role === "user" || role === "assistant") {
+      const sum = summaryOf(body, on(r._compressed_summary))
+      if (sum) {
+        if (sum.summary) turns.push({ kind: "compaction", ...stamp, summary: sum.summary })
+        body = sum.prior ?? ""
+      }
+    }
+    const parts = typeof content === "string" ? [] : content
+    const others = (keep: (p: Part) => boolean) => parts.filter((p) => p.type !== "text" && !keep(p))
+
+    if (role === "user") {
+      if (!prompted) {
+        const note = body.match(CONTINUED_NOTE)
+        if (note) {
+          // The note brain puts before the first message it carries over, not something the person wrote.
+          h.parent ??= { id: note[1]!, kind: "continued" }
+          body = body.replace(/^\[This session continues [^\n]*\]/, "").trimStart()
+        }
+      }
+      const attachments: Attachment[] = []
+      for (const p of parts) {
+        const url = imageUrlOf(p)
+        if (url === undefined) continue
+        const data = parseDataUrl(url)
+        const kept = data ? keepImage(data.base64, data.mime) : undefined
+        if (kept) attachments.push(kept)
+        else lost.add("images")
+      }
+      for (const p of others((p) => imageUrlOf(p) !== undefined)) lost.add(`unknown content parts: ${String(p.type)}`)
+      if (body.trim() || attachments.length) {
+        turns.push({ kind: "user", ...stamp, text: body, ...(attachments.length ? { attachments } : {}) })
+        prompted = true
+      }
+      continue
+    }
+
+    if (role === "assistant") {
+      // Hermes keeps readable reasoning in `reasoning` (and copies it to reasoning_content for providers that
+      // want it echoed); reasoning_details and Codex reasoning items carry signed or encrypted reasoning.
+      const reasoning = [r.reasoning, r.reasoning_content].find((v) => typeof v === "string" && v.trim()) as string | undefined
+      const details = json(r.reasoning_details)
+      if (reasoning) turns.push({ kind: "reasoning", ...stamp, text: reasoning })
+      if (signedDetails(details)) lost.add(reasoning ? "reasoning signatures" : "signed reasoning")
+      if (json(r.codex_reasoning_items)) lost.add("encrypted reasoning")
+      for (const p of others(() => false)) lost.add(`unknown content parts: ${String(p.type)}`)
+      if (body.trim()) turns.push({ kind: "assistant", ...stamp, text: body })
+      const calls = r.tool_calls ? json(r.tool_calls) : []
+      if (!Array.isArray(calls)) {
+        lost.add("unreadable tool calls")
+        continue
+      }
+      for (const c of calls as Row[]) {
+        const fn = (c?.function ?? {}) as Row
+        const stored = text(c?.id) ?? text(c?.call_id) ?? ""
+        const name = text(fn.name) ?? "unknown"
+        let callId = stored
+        for (let n = 2; !callId || emitted.has(callId); n++) callId = `${stored || "call"}#${n}`
+        emitted.add(callId)
+        waiting.set(stored, [...(waiting.get(stored) ?? []), callId])
+        if (c?.extra_content) lost.add("provider signatures on tool calls")
+        turns.push({ kind: "tool_call", ...stamp, id: callId, name, toolKind: hermesToolKind(name), input: argsOf(fn.arguments) })
+      }
+      continue
+    }
+
+    if (role === "tool") {
+      const stored = text(r.tool_call_id) ?? ""
+      const queue = waiting.get(stored)
+      const callId = queue?.shift()
+      if (!callId) {
+        lost.add(emitted.has(stored) ? "repeated tool results" : "tool results without a call")
+        continue
+      }
+      const images = parts.filter((p) => imageUrlOf(p) !== undefined).length
+      if (images) lost.add("images in tool results", images)
+      const out = toolOutput(content)
+      const c = clip(out.text)
+      turns.push({ kind: "tool_result", ...stamp, callId, ok: out.ok, output: c.text, ...(c.truncated ? { truncated: true } : {}) })
+      continue
+    }
+
+    lost.add(`messages with role ${role || "(none)"}`)
+  }
+  lost.flush(h)
+  const updatedAt = latest(last, s.ended_at, s.last_activity_at, s.started_at)
+  if (updatedAt) h.updatedAt = updatedAt
+  return { header: h, turns }
+}
+
+export const hermesReader: Reader = {
+  tool: TOOL,
+  label: LABEL,
+  async list(home) {
+    const db = storePath(home)
+    if (!exists(db)) return []
+    try {
+      return withSnapshot(db, (d) => listHermes(d, db)).sort((a, b) => (b.updatedAt ?? "").localeCompare(a.updatedAt ?? ""))
+    } catch {
+      // A store that cannot be copied or opened lists nothing; read() says why.
+      return []
+    }
+  },
+  async read(ref, home) {
+    if (!exists(ref.path)) throw new Error(`Hermes session store not found: ${ref.path}`)
+    return withSnapshot(ref.path, (d) => readHermes(d, ref.sourceId, { path: ref.path, home }))
+  },
+}