@100xprompt/brain 0.0.0-stage → 0.1.0

package/src/adapters/hermes/writer.ts

@@ -0,0 +1,452 @@
+import { Database } from "bun:sqlite"
+import { mkdirSync } from "node:fs"
+import { basename, join, resolve } from "node:path"
+import { toolLabel } from "../../brief.ts"
+import { exists, gitInfo, isDir } from "../../fsutil.ts"
+import type { Session, Turn } from "../../session/types.ts"
+import { countTurns, firstUserText, unpaired } from "../../session/util.ts"
+import { withSnapshot } from "../../sqlite.ts"
+import { continuedNote } from "../opencode/note.ts"
+import { random62 } from "../opencode/ids.ts"
+import { sh } from "../opencode/writer.ts"
+import type { Readiness, WriteOptions, WriteResult, Writer } from "../types.ts"
+import { readHermes } from "./reader.ts"
+import {
+  LABEL,
+  MAX_SCHEMA,
+  MIN_SCHEMA,
+  SESSION_ID,
+  TESTED_VERSIONS,
+  TOOL,
+  columnsOf,
+  hermesBin,
+  hermesCall,
+  hermesVersion,
+  newSessionId,
+  pyJson,
+  responseItemId,
+  schemaVersion,
+  storePath,
+  summaryText,
+  toolContent,
+} from "./records.ts"
+
+// Continues a portable session in Hermes Agent as a new session of its own store, ~/.hermes/state.db, with the
+// rows Hermes itself writes (SessionDB.append_message / _insert_message_rows in hermes_state.py): a user row per
+// prompt, an assistant row per model response (its text, readable reasoning in `reasoning`, its calls as an
+// OpenAI `tool_calls` list), and a `tool` row per result right after the call that asked for it. The note saying
+// where the session came from opens the first prompt the model sees, as Hermes opens a prompt with its own
+// image-fallback notes. A compaction is written as Hermes compacts (archive_and_compact): the turns before the
+// last summary are kept but out of the replay (active = 0, compacted = 1), then the summary as a user message
+// with Hermes's legacy summary prefix (flagged _compressed_summary where the store has that column).
+//
+// session-migrate installs through Hermes's own SessionDB.import_sessions; this writer inserts the same rows
+// itself, in one immediate transaction, setting only columns the target store has, so it writes the schema-19
+// store of Hermes 0.18.2 and the schema-26 store of 0.20.6 alike; the store's own triggers keep its FTS5 indexes
+// in sync. The session is read back inside the transaction and rolled back unless it reads as written. Hermes
+// shares the store between its CLI, gateway and cron processes (WAL, short write transactions with retries), so
+// a new session can go in while Hermes runs, as its own processes do; when the store stays locked the write is
+// refused. The store is backed up first with SQLite's VACUUM INTO, a consistent copy even with Hermes running.
+// A missing store is not created: Hermes creates and migrates its own schema the first time it runs.
+
+const NO_RESULT = "No result was recorded for this call; the session moved before it finished."
+
+/** The columns the writer cannot do without; anything else is written only where the store has it. */
+const NEEDED = {
+  sessions: ["id", "source", "model", "parent_session_id", "started_at", "ended_at", "end_reason", "message_count", "tool_call_count", "cwd", "title"],
+  messages: ["id", "session_id", "role", "content", "tool_call_id", "tool_calls", "tool_name", "timestamp", "finish_reason", "reasoning", "active", "compacted"],
+}
+
+/** One messages row before it is inserted (columns the store lacks are left out then). */
+export interface MessageRow {
+  role: "user" | "assistant" | "tool"
+  content: string
+  tool_call_id: string | null
+  tool_calls: string | null
+  tool_name: string | null
+  timestamp: number
+  finish_reason: string | null
+  reasoning: string | null
+  observed: 0
+  active: 0 | 1
+  compacted: 0 | 1
+  _compressed_summary: 0 | 1
+}
+
+export interface HermesPlan {
+  id: string
+  /** The title before it is made unique in the store (Hermes keeps titles unique: "title #2"). */
+  title: string
+  model: string | null
+  /** When the session is created (seconds): its start, as its id says, though its messages keep their own times. */
+  createdAt: number
+  messages: MessageRow[]
+  lost: string[]
+  /** What a read-back must find among the replayed (active) rows. */
+  expect: { users: number; assistants: number; calls: number; reasoning: number; compactions: number }
+}
+
+const clean = (s: string) =>
+  s
+    .replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f\u200b-\u200f\u2028-\u202e\u2060-\u2069\ufeff\ufffc\ufff9-\ufffb]/g, "")
+    .replace(/\s+/g, " ")
+    .trim()
+
+/** The session's title marked with where it came from, within Hermes's 100 characters (with room for " #N"). */
+export function hermesTitle(s: Session, label: string): string {
+  const suffix = ` (from ${label})`
+  const room = 100 - suffix.length - 5
+  const base = clean(s.header.title ?? firstUserText(s) ?? "") || "Continued session"
+  return `${base.length > room ? `${base.slice(0, room - 1).trimEnd()}…` : base}${suffix}`
+}
+
+/** The rows of a new Hermes session continuing `session`. Pure: reads and writes nothing. */
+export function planHermes(session: Session, opts: { id: string; now: Date }): HermesPlan {
+  const drops = new Map<string, number>()
+  const drop = (what: string, n = 1) => drops.set(what, (drops.get(what) ?? 0) + n)
+  const turns = session.turns as Turn[]
+  const label = session.header.tool === TOOL ? LABEL : toolLabel(session.header.tool)
+  const lastCompaction = turns.map((t) => t.kind).lastIndexOf("compaction")
+  const expect = { users: 0, assistants: 0, calls: 0, reasoning: 0, compactions: 0 }
+  const messages: MessageRow[] = []
+
+  // Times are seconds and never go backwards (Hermes replays in id order, but lists and searches by time).
+  const known = turns.map((t) => (t.at ? Date.parse(t.at) : Number.NaN)).find(Number.isFinite)
+  let clock = (Date.parse(session.header.startedAt ?? "") || known || opts.now.getTime() - turns.length * 1000) / 1000 - 0.001
+  const tick = (at?: string) => {
+    const t = at ? Date.parse(at) / 1000 : Number.NaN
+    clock = Number.isFinite(t) && t > clock ? t : clock + 0.001
+    return clock
+  }
+  const row = (r: Pick<MessageRow, "role" | "content"> & Partial<MessageRow>, at: number, archived: boolean): MessageRow => ({
+    tool_call_id: null,
+    tool_calls: null,
+    tool_name: null,
+    finish_reason: null,
+    reasoning: null,
+    observed: 0,
+    _compressed_summary: 0,
+    ...r,
+    timestamp: at,
+    active: archived ? 0 : 1,
+    compacted: archived ? 1 : 0,
+  })
+
+  // The first result of every call, written right after the call (OpenAI order), wherever it sat in the source.
+  const callIds = new Set(turns.filter((t) => t.kind === "tool_call").map((t) => (t as Extract<Turn, { kind: "tool_call" }>).id))
+  const results = new Map<string, Extract<Turn, { kind: "tool_result" }>>()
+  for (const t of turns) if (t.kind === "tool_result" && callIds.has(t.callId) && !results.has(t.callId)) results.set(t.callId, t)
+
+  // Tool-call ids go to the provider on every replay: ids providers reject are replaced (results follow their call).
+  const used = new Set<string>()
+  let replaced = 0
+  const idFor = (src: string) => {
+    let id = /^[A-Za-z0-9_-]{1,64}$/.test(src) && !used.has(src) ? src : ""
+    if (!id) {
+      replaced++
+      do id = `call_${random62(24)}`
+      while (used.has(id))
+    }
+    used.add(id)
+    return id
+  }
+
+  const note = continuedNote(label, session.header.id, opts.now.toISOString().slice(0, 10))
+  let noted = false
+  const noteRow = () => {
+    messages.push(row({ role: "user", content: note }, tick(), false))
+    noted = true
+  }
+
+  type Pending = { src: string; id: string; name: string; terminal: boolean }
+  let step: { row: MessageRow; text: string[]; reasoning: string[]; calls: Array<Record<string, unknown>>; pending: Pending[]; archived: boolean } | undefined
+  const written = new Set<string>()
+  let renamed = 0
+
+  const open = (archived: boolean, at?: string) => {
+    if (step && step.archived !== archived) close()
+    if (step) return step
+    if (!archived && !noted) noteRow()
+    step = { row: row({ role: "assistant", content: "" }, tick(at), archived), text: [], reasoning: [], calls: [], pending: [], archived }
+    return step
+  }
+  function close() {
+    if (!step) return
+    const { row: r, text, reasoning, calls, pending, archived } = step
+    step = undefined
+    if (!text.length && !calls.length) {
+      drop("reasoning with no reply to attach it to")
+      return
+    }
+    r.content = text.join("\n\n")
+    r.reasoning = reasoning.length ? reasoning.join("\n\n") : null
+    r.tool_calls = calls.length ? pyJson(calls) : null
+    r.finish_reason = calls.length ? "tool_calls" : "stop"
+    messages.push(r)
+    if (!archived) {
+      if (text.length) expect.assistants++
+      if (reasoning.length) expect.reasoning++
+      expect.calls += calls.length
+    }
+    for (const p of pending) {
+      const res = results.get(p.src)
+      if (!res) drop("tool calls with no result, closed as failed")
+      const output = res ? (res.fullPath ? `${res.output}\n\n[Full output: ${res.fullPath}]` : res.output) : NO_RESULT
+      messages.push(
+        row({ role: "tool", content: toolContent(output, res?.ok ?? false, p.terminal), tool_call_id: p.id, tool_name: p.name }, tick(res?.at), archived),
+      )
+    }
+  }
+
+  for (const [i, t] of turns.entries()) {
+    const archived = i < lastCompaction
+    switch (t.kind) {
+      case "user": {
+        // Images travel as their path, which Hermes's vision_analyze tool can open (as its own fallback note does).
+        const extra: string[] = []
+        for (const a of t.attachments ?? []) {
+          if (a.path) {
+            extra.push(a.kind === "image" ? `[The user attached an image: ${a.path}]` : `[The user attached a file: ${a.path}]`)
+            if (a.kind === "image") drop("images (passed as a file path)")
+          } else drop("attachments without their bytes")
+        }
+        let text = [t.text.trim() ? t.text : "", ...extra].filter(Boolean).join("\n\n")
+        if (!text) break
+        close()
+        if (!archived && !noted) {
+          text = `${note}\n\n${text}`
+          noted = true
+        }
+        messages.push(row({ role: "user", content: text }, tick(t.at), archived))
+        if (!archived) expect.users++
+        break
+      }
+      case "assistant": {
+        if (!t.text.trim()) break
+        if (step?.calls.length) close()
+        open(archived, t.at).text.push(t.text)
+        break
+      }
+      case "reasoning": {
+        if (!t.text.trim()) break
+        if (step?.calls.length) close()
+        open(archived, t.at).reasoning.push(t.text)
+        break
+      }
+      case "tool_call": {
+        if (written.has(t.id)) {
+          drop("repeated tool call ids")
+          break
+        }
+        written.add(t.id)
+        const st = open(archived, t.at)
+        const call = hermesCall(t)
+        if (call.mapped) renamed++
+        const id = idFor(t.id)
+        st.calls.push({ id, call_id: id, response_item_id: responseItemId(id), type: "function", function: { name: call.name, arguments: pyJson(call.args) } })
+        st.pending.push({ src: t.id, id, name: call.name, terminal: call.name === "terminal" })
+        break
+      }
+      case "tool_result": {
+        if (!callIds.has(t.callId)) drop("tool results without a call")
+        else if (results.get(t.callId) !== t) drop("repeated tool results")
+        // Its call's response ends here; the result itself is written with the call.
+        else if (step?.pending.some((p) => p.src === t.callId)) close()
+        break
+      }
+      case "compaction": {
+        close()
+        messages.push(row({ role: "user", content: summaryText(t.summary), _compressed_summary: 1 }, tick(t.at), archived))
+        if (!archived) expect.compactions++
+        break
+      }
+      case "file_edit":
+        if (!t.callId) drop("file edits not made by a tool call")
+        break
+      case "subagent":
+        drop("subagent sessions (their call and result are kept)")
+        break
+    }
+  }
+  close()
+  if (!noted && messages.length) noteRow()
+  if (lastCompaction > 0) drop("turns before the last compaction, kept as Hermes's compacted history (not replayed)", lastCompaction)
+
+  // Nothing may sort after the next message Hermes writes, which is stamped now.
+  const late = (messages.at(-1)?.timestamp ?? 0) - opts.now.getTime() / 1000
+  if (late > 0) for (const m of messages) m.timestamp -= late + 0.001
+
+  const lost = [...drops].map(([what, n]) => `${what} (${n})`)
+  if (replaced) lost.push(`tool-call ids replaced with ids providers accept (${replaced})`)
+  if (renamed) lost.push(`tool calls renamed to Hermes's own tools (${renamed})`)
+  if (session.header.models.length > 1) lost.push(`which model wrote each reply: Hermes keeps one model per session (${session.header.models.length} models)`)
+  const usage = turns.filter((t) => t.kind === "assistant" && t.usage).length
+  if (usage) lost.push(`token usage (${usage} replies)`)
+  return { id: opts.id, title: hermesTitle(session, label), model: session.header.models.at(-1) ?? null, createdAt: opts.now.getTime() / 1000, messages, lost, expect }
+}
+
+/** The folder of the git repository `cwd` is in, below the home folder, as Hermes records git_repo_root. */
+function repoRoot(cwd: string, home: string): string | undefined {
+  for (let dir = cwd; dir && dir !== "/" && dir !== home; dir = dir.slice(0, dir.lastIndexOf("/"))) if (exists(join(dir, ".git"))) return dir
+  return undefined
+}
+
+/** Hermes's title rule (get_next_title_in_lineage): a title in use becomes "title #N", one past the highest N. */
+function uniqueTitle(db: Database, title: string): string {
+  const esc = title.replace(/\\/g, "\\\\").replace(/%/g, "\\%").replace(/_/g, "\\_")
+  const taken = (db.query("SELECT title FROM sessions WHERE title = ? OR title LIKE ? ESCAPE '\\'").all(title, `${esc} #%`) as Array<{ title: string }>).map((r) => r.title)
+  if (!taken.length) return title
+  const n = Math.max(1, ...taken.map((t) => Number(t.match(/ #(\d+)$/)?.[1] ?? 1)))
+  return `${title} #${n + 1}`
+}
+
+/** Why a store cannot take a new session, or nothing when it can. */
+function storeProblem(d: Database, path: string): string | undefined {
+  const v = schemaVersion(d)
+  if (v === undefined) return `the Hermes store at ${path} has no schema version; it is not a store this writer knows`
+  if (v > MAX_SCHEMA) return `the Hermes store at ${path} was migrated by a newer Hermes (schema ${v}; this writer knows ${MIN_SCHEMA} to ${MAX_SCHEMA})`
+  if (v < MIN_SCHEMA) return `the Hermes store at ${path} has an older schema (${v}); run hermes once so it migrates its store`
+  for (const [table, cols] of Object.entries(NEEDED)) {
+    const have = columnsOf(d, table)
+    const missing = cols.filter((c) => !have.has(c))
+    if (missing.length) return `the Hermes store at ${path} has no ${table}.${missing.join(", ")}; it is not a store this writer knows`
+  }
+  return undefined
+}
+
+const noStore = (path: string) => `Hermes has no session store at ${path} yet; run hermes once so it creates and migrates its own, then try again`
+
+const stamp = (d: Date) => d.toISOString().replace(/[:.]/g, "-")
+
+/** The Hermes writer; `newId` and `busyMs` are for tests. */
+export function hermesWriter(opts: { newId?: (now: Date) => string; busyMs?: number } = {}): Writer {
+  return {
+    tool: TOOL,
+    label: LABEL,
+    way: "native",
+
+    async ready(o: WriteOptions): Promise<Readiness> {
+      const bin = hermesBin(o.home)
+      if (!bin) return { ok: false, why: "Hermes Agent is not installed (no hermes on PATH or in ~/.local/bin)" }
+      const v = hermesVersion(bin.path)
+      if (!v) return { ok: false, why: `\`${bin.path} --version\` did not say which Hermes Agent it is` }
+      if (!TESTED_VERSIONS.includes(v)) return { ok: false, why: `Hermes Agent ${v} is not a version this writer was checked against (${TESTED_VERSIONS.join(", ")})` }
+      if (!isDir(o.cwd)) return { ok: false, why: `the folder to continue in does not exist: ${o.cwd}` }
+      const db = storePath(o.home)
+      if (!exists(db)) return { ok: false, why: noStore(db) }
+      try {
+        const problem = withSnapshot(db, (d) => storeProblem(d, db))
+        if (problem) return { ok: false, why: problem }
+      } catch (e) {
+        return { ok: false, why: `the Hermes store at ${db} cannot be read: ${(e as Error).message}` }
+      }
+      return { ok: true }
+    },
+
+    async write(session: Session, o: WriteOptions): Promise<WriteResult> {
+      const cwd = resolve(o.cwd)
+      const now = new Date()
+      const db = storePath(o.home)
+      const plan = planHermes(session, { id: (opts.newId ?? newSessionId)(now), now })
+      if (!SESSION_ID.test(plan.id)) throw new Error(`not a Hermes session id: ${plan.id}`)
+      if (!plan.expect.users && !plan.expect.assistants && !plan.expect.calls && !plan.expect.compactions)
+        throw new Error("the session has no messages to carry over to Hermes")
+      if (!exists(db)) throw new Error(noStore(db))
+      const backupDir = join(o.home, ".brain", "backups", TOOL, stamp(now))
+      const command = hermesBin(o.home)?.command ?? "hermes"
+      const result = (title: string): WriteResult => ({
+        tool: TOOL,
+        way: "native",
+        sessionId: plan.id,
+        written: [db, backupDir],
+        open: `cd ${sh(cwd)} && ${sh(command)} chat --resume ${plan.id}`,
+        note: `Hermes lists it as "${title}".`,
+        lost: plan.lost,
+        dryRun: !!o.dryRun,
+      })
+      if (o.dryRun) {
+        const problem = withSnapshot(db, (d) => storeProblem(d, db))
+        if (problem) throw new Error(problem)
+        return result(plan.title)
+      }
+      return result(insert(db, plan, { cwd, home: o.home, backupDir, busyMs: opts.busyMs ?? 5000, source: session.header.id }))
+    },
+  }
+}
+
+export const hermesNativeWriter = hermesWriter()
+
+const isBusy = (e: unknown) => /SQLITE_BUSY|database is locked/i.test(`${(e as { code?: string }).code ?? ""} ${(e as Error).message ?? ""}`)
+
+/** Backs the store up, writes the session in one transaction and reads it back before committing. Returns the title. */
+function insert(dbPath: string, plan: HermesPlan, o: { cwd: string; home: string; backupDir: string; busyMs: number; source: string }): string {
+  const db = new Database(dbPath)
+  try {
+    db.exec(`PRAGMA busy_timeout = ${Math.max(0, Math.floor(o.busyMs))}`)
+    db.exec("PRAGMA foreign_keys = ON")
+    const problem = storeProblem(db, dbPath)
+    if (problem) throw new Error(problem)
+    mkdirSync(o.backupDir, { recursive: true, mode: 0o700 })
+    db.exec(`VACUUM INTO '${join(o.backupDir, basename(dbPath)).replace(/'/g, "''")}'`)
+
+    const sCols = columnsOf(db, "sessions")
+    const mCols = columnsOf(db, "messages")
+    const git = gitInfo(o.cwd, o.home)
+    const root = git.gitBranch ? repoRoot(o.cwd, o.home) : undefined
+    const live = plan.messages.filter((m) => m.active)
+    let title = plan.title
+
+    db.transaction(() => {
+      if (db.query("SELECT 1 FROM sessions WHERE id = ?").get(plan.id)) throw new Error(`Hermes already has a session ${plan.id}; nothing was written`)
+      title = uniqueTitle(db, plan.title)
+      const session: Record<string, unknown> = {
+        id: plan.id,
+        source: "cli",
+        model: plan.model,
+        started_at: plan.createdAt,
+        ended_at: plan.createdAt,
+        end_reason: "brain_import",
+        message_count: live.length,
+        tool_call_count: live.reduce((n, m) => n + (m.tool_calls ? (JSON.parse(m.tool_calls) as unknown[]).length : 0), 0),
+        cwd: o.cwd,
+        title,
+        ...(git.gitBranch ? { git_branch: git.gitBranch } : {}),
+        ...(root ? { git_repo_root: root } : {}),
+      }
+      const keys = Object.keys(session).filter((k) => sCols.has(k))
+      db.prepare(`INSERT INTO sessions (${keys.map((k) => `"${k}"`).join(", ")}) VALUES (${keys.map(() => "?").join(", ")})`).run(...(keys.map((k) => session[k] ?? null) as any[]))
+      const mKeys = ["session_id", ...Object.keys(plan.messages[0]!)].filter((k) => mCols.has(k))
+      const add = db.prepare(`INSERT INTO messages (${mKeys.map((k) => `"${k}"`).join(", ")}) VALUES (${mKeys.map(() => "?").join(", ")})`)
+      for (const m of plan.messages) {
+        const values: Record<string, unknown> = { ...m, session_id: plan.id }
+        add.run(...(mKeys.map((k) => values[k] ?? null) as any[]))
+      }
+      // Read back as the reader reads Hermes; throwing here rolls everything back.
+      const back = readHermes(db, plan.id, { path: dbPath, home: o.home })
+      const n = countTurns(back)
+      const pairs = unpaired(back)
+      const e = plan.expect
+      if (
+        n.user !== e.users ||
+        n.assistant !== e.assistants ||
+        n.tool_call !== e.calls ||
+        n.tool_result !== e.calls ||
+        n.reasoning !== e.reasoning ||
+        n.compaction !== e.compactions ||
+        pairs.calls.length ||
+        pairs.results.length ||
+        back.header.parent?.id !== o.source
+      )
+        throw new Error(
+          `the Hermes session did not read back as written (users ${n.user}/${e.users}, replies ${n.assistant}/${e.assistants}, tool calls ${n.tool_call}/${e.calls}, results ${n.tool_result}/${e.calls}, reasoning ${n.reasoning}/${e.reasoning}, summaries ${n.compaction}/${e.compactions}, unpaired ${pairs.calls.length + pairs.results.length}); nothing was kept`,
+        )
+    }).immediate()
+    db.exec("PRAGMA wal_checkpoint(PASSIVE)")
+    return title
+  } catch (e) {
+    if (isBusy(e)) throw new Error(`Hermes is holding its session store (${dbPath} is locked); try again when it is idle. Nothing was written.`)
+    throw e
+  } finally {
+    db.close()
+  }
+}

package/src/adapters/iflow-cli/index.ts

@@ -0,0 +1,72 @@
+import { join } from "node:path"
+import { isDir, ls, mtime } from "../../fsutil.ts"
+import type { Session } from "../../session/types.ts"
+import { header, iso, lossCounter } from "../../session/util.ts"
+import type { Reader, SessionRef, Writer } from "../types.ts"
+import { type IflowRecord, LABEL, readRecords, recordsToTurns, stripNote, TOOL } from "./records.ts"
+import { iflowNativeWriter } from "./writer.ts"
+
+// iFlow CLI keeps each project's sessions in ~/.iflow/projects/<project name>/<session id>.jsonl, where the
+// session id is session-<uuid> (records.ts has the format). Its list is every .jsonl in the project's folder,
+// newest activity first; a session has no title, so the list shows its first request.
+
+const oneLine = (s: string) => s.replace(/\s+/g, " ").trim()
+
+function firstRequest(records: IflowRecord[]): string | undefined {
+  for (const r of records) {
+    if (r.type !== "user" || r.isMeta || r.toolUseResult || r.isCompactSummary) continue
+    const c = r.message.content
+    const text = typeof c === "string" ? c : Array.isArray(c) ? c.map((b) => (b.type === "text" ? b.text : "")).join("") : ""
+    const t = oneLine(stripNote(text).text)
+    if (t) return t.slice(0, 120)
+  }
+  return undefined
+}
+
+export const reader: Reader = {
+  tool: TOOL,
+  label: LABEL,
+
+  async list(home) {
+    const projects = join(home, ".iflow", "projects")
+    if (!isDir(projects)) return []
+    const refs: SessionRef[] = []
+    for (const project of ls(projects)) {
+      for (const name of ls(join(projects, project))) {
+        if (!name.endsWith(".jsonl")) continue
+        const path = join(projects, project, name)
+        const { records } = readRecords(path)
+        if (!records.length) continue
+        const cwd = records.find((r) => r.cwd)?.cwd
+        const title = firstRequest(records)
+        const updatedAt = iso(records[records.length - 1]!.timestamp) ?? mtime(path)
+        refs.push({ tool: TOOL, sourceId: name.replace(/\.jsonl$/, ""), path, ...(title ? { title } : {}), ...(cwd ? { cwd } : {}), ...(updatedAt ? { updatedAt } : {}), extra: { project } })
+      }
+    }
+    return refs.sort((a, b) => (b.updatedAt ?? "").localeCompare(a.updatedAt ?? ""))
+  },
+
+  async read(ref) {
+    const { records, bad } = readRecords(ref.path)
+    if (!records.length) throw new Error(`${ref.path} holds no iFlow CLI records`)
+    const lost = lossCounter()
+    if (bad) lost.add("unreadable lines", bad)
+    const first = records[0]!
+    const cwd = records.find((r) => r.cwd)?.cwd
+    const branch = records.find((r) => r.gitBranch)?.gitBranch
+    const title = firstRequest(records)
+    const h = header(TOOL, ref.sourceId, {
+      sourcePath: ref.path,
+      project: { ...(cwd ? { cwd } : {}), ...(branch ? { gitBranch: branch } : {}) },
+      ...(title ? { title } : {}),
+      ...(iso(first.timestamp) ? { startedAt: iso(first.timestamp) } : {}),
+      ...(iso(records[records.length - 1]!.timestamp) ? { updatedAt: iso(records[records.length - 1]!.timestamp) } : {}),
+    })
+    const turns = recordsToTurns(records, h, lost)
+    lost.flush(h)
+    return { header: h, turns } satisfies Session
+  },
+}
+
+export const readers: Reader[] = [reader]
+export const writers: Writer[] = [iflowNativeWriter]