@100xprompt/brain 0.0.0-stage → 0.1.1

package/src/adapters/aider/records.ts

@@ -0,0 +1,220 @@
+import { mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs"
+import { dirname, join } from "node:path"
+import { exists, isDir, versionOf } from "../../fsutil.ts"
+
+// What Aider's chat history looks like, as far as this adapter relies on it. Checked against aider-chat
+// 0.86.2 (PyPI) and its source at Aider-AI/aider 5dc9490 (aider/io.py, aider/utils.py,
+// aider/coders/base_coder.py, aider/args.py, aider/history.py). Catalogue entry 13.
+//
+// Aider keeps one Markdown file per project, `.aider.chat.history.md` at the git root (else the folder it
+// runs in), and appends to it for ever: each launch writes "# aider chat started at <local time>", the
+// person's input as "#### " lines, Aider's own notices as "> " lines and the model's replies as plain
+// text. `aider --restore-chat-history` reads the whole file back with utils.split_chat_history_markdown:
+// "# " lines are skipped, "> " lines are dropped (they are its own output, never sent to the model), runs
+// of "#### " lines are one user message, and everything else is the assistant's. There are no ids, no tool
+// calls and no reasoning.
+
+export const TOOL = "aider"
+export const LABEL = "Aider"
+
+/** Aider versions whose history format the writer was checked against. */
+export const TESTED_VERSIONS = ["0.86.2"]
+
+export const HISTORY_FILE = ".aider.chat.history.md"
+export const INPUT_HISTORY_FILE = ".aider.input.history"
+
+/** The line each Aider launch starts with (io.py: datetime.now().strftime("%Y-%m-%d %H:%M:%S")). */
+export const RUN_HEADER = /^# aider chat started at (\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2})\s*$/
+
+/** What Aider's own summariser puts before a summary that replaced earlier messages (prompts.summary_prefix). */
+export const SUMMARY_PREFIX = "I spoke to you previously about a number of things.\n"
+
+/** The note a continued session opens with; the reader recognises it and records where the session came from. */
+export const continuedNote = (label: string, id: string, when: string) =>
+  `[This session continues ${label} session ${id}, carried over by brain session on ${when}. The messages below are its history; tool calls are shown as text, and reasoning and anything listed as lost did not carry over. Check files before relying on details, since they may have changed.]`
+export const CONTINUED_NOTE = /^\[This session continues .+? session (\S+), carried over by brain session/
+
+/** The installed Aider version ("aider 0.86.2" → "0.86.2"), or undefined when it is missing. */
+export const aiderVersion = (bin = "aider") => versionOf(bin)?.match(/(\d+\.\d+\.\d+(?:\.dev\d*)?)/)?.[1]
+
+/**
+ * The folder Aider keeps its history in for `cwd`: the enclosing git working tree (args.py defaults the
+ * history files to the git root; main.get_git_root searches parent folders), else `cwd` itself.
+ */
+export function historyRoot(cwd: string): string {
+  let dir = cwd.replace(/\/+$/, "") || "/"
+  for (let i = 0; i < 40; i++) {
+    if (exists(join(dir, ".git"))) return dir
+    const up = dir.slice(0, dir.lastIndexOf("/")) || "/"
+    if (up === dir) break
+    dir = up
+  }
+  return cwd
+}
+
+/** Line breaks Python's str.splitlines() splits on; the parser sees each as a new line. */
+const PY_LINE_BREAKS = /\r\n|[\n\r\v\f\x1c\x1d\x1e\x85\u2028\u2029]/
+
+/** Text split into lines the way split_chat_history_markdown splits it, without the line endings. */
+export const pyLines = (text: string) => text.split(PY_LINE_BREAKS)
+
+/** One message as Aider's parser yields it. */
+export interface MdMessage {
+  role: "user" | "assistant" | "tool"
+  content: string
+}
+
+/** One launch of Aider: its header time and its messages, tool lines included. */
+export interface Run {
+  startedAt?: string
+  /** 0-based index of the run in the file. */
+  index: number
+  messages: MdMessage[]
+}
+
+/**
+ * The file split into runs, each parsed exactly as utils.split_chat_history_markdown parses (with
+ * include_tool=True, so the reader can see Aider's notices; the model never gets the "tool" ones).
+ */
+export function parseRuns(text: string): Run[] {
+  const runs: Run[] = []
+  let run: Run = { index: 0, messages: [] }
+  let user: string[] = []
+  let assistant: string[] = []
+  let tool: string[] = []
+  const append = (role: MdMessage["role"], lines: string[]) => {
+    const content = lines.join("")
+    if (content.trim()) run.messages.push({ role, content })
+  }
+  const flushAll = () => {
+    append("assistant", assistant)
+    append("user", user)
+    append("tool", tool)
+    assistant = []
+    user = []
+    tool = []
+  }
+  const parts = text.split(/(\r\n|[\n\r\v\f\x1c\x1d\x1e\x85\u2028\u2029])/)
+  for (let i = 0; i < parts.length; i += 2) {
+    const body = parts[i]!
+    const line = body + (parts[i + 1] ?? "")
+    if (!line) continue
+    const header = body.match(RUN_HEADER)
+    if (header) {
+      // A new launch: Aider's parser would carry on across it, but the reader keeps each launch apart.
+      flushAll()
+      if (run.messages.length || run.startedAt) runs.push(run)
+      run = { index: runs.length, startedAt: header[1]!, messages: [] }
+      continue
+    }
+    if (line.startsWith("# ")) continue
+    if (line.startsWith("> ")) {
+      append("assistant", assistant)
+      assistant = []
+      append("user", user)
+      user = []
+      tool.push(line.slice(2))
+      continue
+    }
+    if (line.startsWith("#### ")) {
+      append("assistant", assistant)
+      assistant = []
+      append("tool", tool)
+      tool = []
+      user.push(line.slice(5))
+      continue
+    }
+    append("user", user)
+    user = []
+    append("tool", tool)
+    tool = []
+    assistant.push(line)
+  }
+  flushAll()
+  if (run.messages.length || run.startedAt) runs.push(run)
+  return runs
+}
+
+/** A user message as the person typed it: Aider ends each "#### " line with a Markdown line break ("  "). */
+export const userText = (content: string) =>
+  pyLines(content)
+    .map((l) => l.replace(/ {2}$/, ""))
+    .join("\n")
+    .replace(/^\n+|\s+$/g, "")
+    .replace(/^<blank>$/, "")
+
+/**
+ * Lines the parser would take for something else get one more leading space from the writer, and lose one
+ * in the reader; lines that already start with spaces before such a marker get one too, so the round trip
+ * is exact.
+ */
+const CLASHES = /^ *(# |#### |> )/
+const ESCAPED = /^ +(# |#### |> )/
+export const escapeLine = (line: string) => (CLASHES.test(line) ? ` ${line}` : line)
+export const unescapeLine = (line: string) => (ESCAPED.test(line) ? line.slice(1) : line)
+
+/** An assistant message as written: the escape spaces taken out, surrounding blank lines trimmed. */
+export const assistantText = (content: string) => pyLines(content).map(unescapeLine).join("\n").trim()
+
+/** Folders the history search never enters: system and package folders that hold no projects. */
+const SKIP_DIRS = new Set(["node_modules", "Library", "Applications", "Pictures", "Music", "Movies", "venv", "__pycache__", "dist", "build", "target", "vendor"])
+
+/**
+ * Every Aider history file in the folders under `home`, at most `depth` levels down. Aider keeps no index
+ * of its projects, so they are found by name; hidden and package folders are skipped and the walk stops
+ * after `budget` folders so listing stays cheap.
+ */
+export function findHistories(home: string, depth = 5, budget = 20_000): string[] {
+  const cache = join(home, ".brain", "cache", "aider-histories.json")
+  const fresh = process.env.BRAIN_NO_CACHE !== "1" ? readCache(cache) : undefined
+  const found = new Set(fresh ?? walkHistories(home, depth, budget))
+  if (!fresh && process.env.BRAIN_NO_CACHE !== "1") writeCache(cache, [...found])
+  // The folder the person is in, and the folders above it, are always checked: a project started since the cache was made is found.
+  for (let dir = process.cwd(), i = 0; i < depth && dir.startsWith(home); dir = dirname(dir), i++) {
+    const p = join(dir, HISTORY_FILE)
+    if (exists(p)) found.add(p)
+  }
+  return [...found]
+}
+
+/** How long a walk of the home folder is trusted. Aider keeps no index, so the walk is the only way to find its projects. */
+const CACHE_TTL_MS = 10 * 60_000
+
+function readCache(file: string): string[] | undefined {
+  try {
+    if (Date.now() - statSync(file).mtimeMs > CACHE_TTL_MS) return undefined
+    const j = JSON.parse(readFileSync(file, "utf8"))
+    return Array.isArray(j?.paths) ? j.paths.filter((p: unknown): p is string => typeof p === "string" && exists(p)) : undefined
+  } catch {
+    return undefined
+  }
+}
+
+function writeCache(file: string, paths: string[]) {
+  try {
+    mkdirSync(dirname(file), { recursive: true })
+    writeFileSync(file, JSON.stringify({ paths }))
+  } catch {}
+}
+
+function walkHistories(home: string, depth: number, budget: number): string[] {
+  const out: string[] = []
+  let left = budget
+  const walk = (dir: string, level: number) => {
+    if (left-- <= 0) return
+    let entries: import("node:fs").Dirent[]
+    try {
+      entries = readdirSync(dir, { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const e of entries) if (e.name === HISTORY_FILE && (e.isFile() || e.isSymbolicLink())) out.push(join(dir, e.name))
+    if (level >= depth) return
+    for (const e of entries) {
+      if (!e.isDirectory() || e.name.startsWith(".") || SKIP_DIRS.has(e.name) || e.name.endsWith(".app")) continue
+      walk(join(dir, e.name), level + 1)
+    }
+  }
+  if (isDir(home)) walk(home, 0)
+  return out
+}

package/src/adapters/aider/writer.ts

@@ -0,0 +1,269 @@
+import { closeSync, ftruncateSync, mkdirSync, openSync, readFileSync, rmSync, statSync, writeSync } from "node:fs"
+import { join, resolve } from "node:path"
+import { toolLabel } from "../../brief.ts"
+import { exists, isDir } from "../../fsutil.ts"
+import type { Session, Turn } from "../../session/types.ts"
+import type { Readiness, WriteOptions, WriteResult, Writer } from "../types.ts"
+import { runId } from "./reader.ts"
+import {
+  HISTORY_FILE,
+  INPUT_HISTORY_FILE,
+  LABEL,
+  SUMMARY_PREFIX,
+  TESTED_VERSIONS,
+  TOOL,
+  aiderVersion,
+  assistantText,
+  continuedNote,
+  escapeLine,
+  historyRoot,
+  parseRuns,
+  pyLines,
+  userText,
+} from "./records.ts"
+
+// Continues a portable session in Aider as a new run appended to the project's chat history
+// (.aider.chat.history.md at the git root, else the folder), written the way Aider's InputOutput writes
+// one: the "# aider chat started at" line, each request as "#### " lines ending in a Markdown line break,
+// each reply as plain text between blank lines. `aider --restore-chat-history` then gives the model the
+// whole file as messages (utils.split_chat_history_markdown), this run included.
+//
+// Why append, not a fresh file with the old one backed up: Aider treats the file as the project's one
+// history. Every launch appends to it and --restore-chat-history replays all of it, so a continued session
+// is one more launch in that history; moving the existing file aside would hide the person's earlier Aider
+// work from Aider, which is modifying another session. Appending leaves every earlier byte as it was, and a
+// run that does not read back is cut off again at the length the file had before.
+//
+// Aider has no record for tool calls or reasoning. Tool calls and their results travel as text inside the
+// reply they belong to (that is what the model would see in an Aider chat anyway: edits and commands live in
+// the reply's text), reasoning is dropped. Lines the parser would misread ("# ", "#### ", "> " at the start
+// of a reply line) get one leading space, which Markdown ignores. A compaction is written the way Aider's
+// own summariser hands one to the model: a user message starting "I spoke to you previously about a number
+// of things." followed by the turns after it. The prompts also go into .aider.input.history, so the arrow
+// keys recall them as they would in Aider.
+
+const shellQuote = (s: string) => (/^[\w./@%+=:,-]+$/.test(s) ? s : `'${s.replace(/'/g, `'\\''`)}'`)
+
+const pad = (n: number, w = 2) => String(n).padStart(w, "0")
+/** Local time as Python's datetime.now().strftime("%Y-%m-%d %H:%M:%S"). */
+const localStamp = (d: Date) => `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`
+/** Local time as str(datetime.now()), which prompt_toolkit's FileHistory writes before each entry. */
+const pyNow = (d: Date) => `${localStamp(d)}.${pad(d.getMilliseconds(), 3)}000`
+
+/** A fence longer than any run of backticks in the text, so the text cannot close it. */
+const fence = (text: string) => "`".repeat(Math.max(3, ...[...text.matchAll(/`+/g)].map((m) => m[0].length + 1)))
+const fenced = (text: string, lang = "") => {
+  const f = fence(text)
+  return `${f}${lang}\n${text.replace(/\n+$/, "")}\n${f}`
+}
+
+/** Text with every line break Aider's parser knows as "\n", so what is written is what reads back. */
+const oneBreak = (text: string) => pyLines(text).join("\n")
+
+type Call = Extract<Turn, { kind: "tool_call" }>
+type Result = Extract<Turn, { kind: "tool_result" }>
+
+/** A tool call and its result as reply text. */
+function callText(call: Call, result: Result | undefined): string {
+  const input = typeof call.input === "string" ? call.input : JSON.stringify(call.input ?? {}, null, 2)
+  const parts = [`[Tool call: ${call.name} (${call.toolKind})]`, fenced(input, typeof call.input === "string" ? "" : "json")]
+  if (!result) parts.push("[No result was recorded for this call.]")
+  else {
+    let out = result.output || "(no output)"
+    if (result.fullPath) out += `\n\n[Full output: ${result.fullPath}]`
+    parts.push(result.ok ? "[Result]" : "[Result: failed]", fenced(out))
+  }
+  return parts.join("\n")
+}
+
+export interface MdPlan {
+  /** The run's text, appended to the history file as it stands. */
+  history: string
+  /** The prompts, in prompt_toolkit FileHistory form, appended to the input history. */
+  input: string
+  /** The messages Aider's parser must find in the run, for the read-back. */
+  messages: Array<{ role: "user" | "assistant"; text: string }>
+  lost: string[]
+}
+
+/** The run that continues `session` in Aider. Pure. */
+export function planRun(session: Session, now: Date): MdPlan {
+  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)
+
+  // From the last compaction on: Aider keeps no compaction in its file, it hands the model the summary instead.
+  let start = 0
+  let summary: string | undefined
+  session.turns.forEach((t, i) => {
+    if (t.kind === "compaction") {
+      start = i + 1
+      summary = t.summary
+    }
+  })
+  const before = session.turns.slice(0, start).filter((t) => t.kind !== "compaction").length
+  if (before) drop("turns before the last compaction, replaced by its summary", before)
+
+  const results = new Map<string, Result>()
+  for (const t of session.turns) if (t.kind === "tool_result" && !results.has(t.callId)) results.set(t.callId, t)
+  const callIds = new Set(session.turns.filter((t) => t.kind === "tool_call").map((t) => (t as Call).id))
+
+  const messages: MdPlan["messages"] = []
+  const prompts: string[] = []
+  let reply: string[] = []
+  const flush = () => {
+    const text = oneBreak(reply.join("\n\n")).trim()
+    if (text) messages.push({ role: "assistant", text })
+    reply = []
+  }
+  const user = (text: string, prompt: boolean) => {
+    flush()
+    messages.push({ role: "user", text: oneBreak(text) })
+    if (prompt) prompts.push(oneBreak(text))
+  }
+
+  user(continuedNote(label, session.header.id, now.toISOString().slice(0, 10)), false)
+  if (summary) user(`${SUMMARY_PREFIX}${summary}`, false)
+  const seen = new Set<string>()
+  for (const t of session.turns.slice(start)) {
+    switch (t.kind) {
+      case "user":
+        if (t.attachments?.length) drop("attachments (Aider's history holds text only)", t.attachments.length)
+        if (t.text.trim()) user(t.text, true)
+        break
+      case "assistant":
+        if (t.text.trim()) reply.push(t.text.trim())
+        break
+      case "tool_call":
+        if (seen.has(t.id)) break
+        seen.add(t.id)
+        reply.push(callText(t, results.get(t.id)))
+        drop("tool calls, kept as text in the replies (Aider has no tool-call record)")
+        if (!results.has(t.id)) drop("tool calls without a result")
+        break
+      case "tool_result":
+        if (!callIds.has(t.callId)) drop("tool results without a call")
+        break
+      case "file_edit":
+        if (t.callId && callIds.has(t.callId)) break
+        reply.push([`[Edited ${t.path}]`, ...(t.patch ? [fenced(t.patch, "diff")] : [])].join("\n"))
+        drop("file edits outside a tool call, kept as text")
+        break
+      case "reasoning":
+        drop("reasoning (Aider's history has no place for it)")
+        break
+      case "subagent":
+        drop("subagent sessions")
+        break
+      case "compaction":
+        break
+    }
+  }
+  flush()
+
+  // As InputOutput writes them: user_input() and ai_output() through append_chat_history().
+  const lines = [`\n# aider chat started at ${localStamp(now)}\n\n`]
+  for (const m of messages) {
+    if (m.role === "user") {
+      const body = pyLines(m.text).join("  \n#### ").replace(/\s+$/, "")
+      lines.push(`\n#### ${body}  \n`)
+    } else {
+      lines.push(`\n${pyLines(m.text).map(escapeLine).join("\n")}\n\n`)
+    }
+  }
+  const input = prompts.map((p) => `\n# ${pyNow(now)}\n${p.split("\n").map((l) => `+${l}\n`).join("")}`).join("")
+  return { history: lines.join(""), input, messages, lost: [...drops].map(([what, n]) => `${what} (${n})`) }
+}
+
+/** Appends `text` to `path` and returns how long the file was before, so a failed run can be cut off again. */
+function append(path: string, text: string): number {
+  const size = exists(path) ? statSync(path).size : -1
+  const fd = openSync(path, "a")
+  try {
+    writeSync(fd, text)
+  } finally {
+    closeSync(fd)
+  }
+  return size
+}
+
+/** Puts a file back to the length it had (or removes it when it did not exist). */
+function restore(path: string, size: number) {
+  if (size < 0) return rmSync(path, { force: true })
+  const fd = openSync(path, "r+")
+  try {
+    ftruncateSync(fd, size)
+  } finally {
+    closeSync(fd)
+  }
+}
+
+/**
+ * Whether an Aider is running: its command line runs the `aider` script (a pip install runs it through Python,
+ * so the process name is not "aider"). A running Aider appends its own lines to the history it has open, and
+ * lines it wrote after the continued run would read as part of it.
+ */
+function aiderRunning(): boolean {
+  try {
+    return Bun.spawnSync(["pgrep", "-f", "(^|/)aider( |$)"], { stdout: "pipe", stderr: "pipe" }).exitCode === 0
+  } catch {
+    return false
+  }
+}
+
+/** The Aider writer; `version` and `running` are for tests, which must not depend on an installed Aider. */
+export function aiderWriter(opts: { version?: string; running?: () => boolean } = {}): Writer {
+  const installed = () => opts.version ?? aiderVersion()
+  const running = opts.running ?? aiderRunning
+  return {
+    tool: TOOL,
+    label: LABEL,
+    way: "native",
+
+    async ready(w: WriteOptions): Promise<Readiness> {
+      const v = installed()
+      if (!v) return { ok: false, why: "Aider is not installed (`aider --version` did not run)" }
+      if (!TESTED_VERSIONS.includes(v)) return { ok: false, why: `Aider ${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; Aider keeps its history in the project` }
+      if (running()) return { ok: false, why: "Aider is running; quit it first, or its next lines would land inside the continued session's history" }
+      return { ok: true }
+    },
+
+    async write(session: Session, w: WriteOptions): Promise<WriteResult> {
+      const cwd = resolve(w.cwd)
+      const root = historyRoot(cwd)
+      const historyPath = join(root, HISTORY_FILE)
+      const inputPath = join(root, INPUT_HISTORY_FILE)
+      const plan = planRun(session, new Date())
+      let sessionId: string | undefined
+      if (!w.dryRun) {
+        mkdirSync(root, { recursive: true })
+        const historySize = append(historyPath, plan.history)
+        // Read back as Aider will: the last run must hold exactly the messages planned.
+        const runs = parseRuns(readFileSync(historyPath, "utf8"))
+        const got = (runs[runs.length - 1]?.messages ?? []).filter((m) => m.role !== "tool")
+        const same =
+          got.length === plan.messages.length &&
+          got.every((m, i) => m.role === plan.messages[i]!.role && (m.role === "user" ? userText(m.content) : assistantText(m.content)).trim() === plan.messages[i]!.text.trim())
+        if (!same) {
+          restore(historyPath, historySize)
+          throw new Error(`the Aider history did not read back as written (${got.length} of ${plan.messages.length} messages); the file was put back as it was`)
+        }
+        if (plan.input) append(inputPath, plan.input)
+        const run = runs[runs.length - 1]!
+        sessionId = runId(historyPath, run, runs)
+      }
+      return {
+        tool: TOOL,
+        way: "native",
+        ...(sessionId ? { sessionId } : {}),
+        written: plan.input ? [historyPath, inputPath] : [historyPath],
+        open: `cd ${shellQuote(cwd)} && aider --restore-chat-history`,
+        lost: plan.lost,
+        dryRun: !!w.dryRun,
+      }
+    },
+  }
+}
+
+export const aiderNativeWriter = aiderWriter()

package/src/adapters/amazon-q-cli/index.ts

@@ -0,0 +1,8 @@
+import type { Reader, Writer } from "../types.ts"
+import { amazonQCliReader } from "./reader.ts"
+import { amazonQCliNativeWriter } from "./writer.ts"
+
+// Amazon Q Developer CLI (`q chat`, superseded by Kiro CLI): reads the per-folder conversations in
+// data.sqlite3 and continues any session as the folder's conversation, which `q chat --resume` restores.
+export const readers: Reader[] = [amazonQCliReader]
+export const writers: Writer[] = [amazonQCliNativeWriter]

package/src/adapters/amazon-q-cli/reader.ts

@@ -0,0 +1,84 @@
+import type { Database } from "bun:sqlite"
+import { exists, gitInfo } from "../../fsutil.ts"
+import { withSnapshot } from "../../sqlite.ts"
+import type { Session } from "../../session/types.ts"
+import { header, iso } from "../../session/util.ts"
+import type { Reader, SessionRef } from "../types.ts"
+import { type ConversationState, LABEL, TOOL, dbPath, turnsOf } from "./records.ts"
+
+// Amazon Q CLI: one conversation per folder in data.sqlite3's `conversations` table, read from a copy with its
+// write-ahead log. Only conversations with history are listed: those are the ones `q chat --resume` restores.
+
+const firstPrompt = (s: ConversationState) => {
+  for (const e of s.history ?? []) {
+    const c = e.user?.content as Record<string, any> | undefined
+    const p = c?.Prompt?.prompt ?? c?.CancelledToolUses?.prompt
+    if (typeof p === "string" && p.trim()) return p.replace(/\s+/g, " ").trim().slice(0, 80)
+  }
+  return undefined
+}
+
+const lastTime = (s: ConversationState) => {
+  for (let i = (s.history?.length ?? 0) - 1; i >= 0; i--) {
+    const t = iso(s.history[i]!.user?.timestamp)
+    if (t) return t
+  }
+  return undefined
+}
+
+function rows(d: Database): Array<{ key: string; state: ConversationState }> {
+  const out: Array<{ key: string; state: ConversationState }> = []
+  for (const r of d.query("SELECT key, value FROM conversations").all() as Array<{ key: string; value: string }>) {
+    try {
+      const state = JSON.parse(r.value) as ConversationState
+      if (Array.isArray(state.history) && state.history.length) out.push({ key: r.key, state })
+    } catch {}
+  }
+  return out
+}
+
+/** The conversation stored for `key`, as a portable session. */
+export function readQ(d: Database, path: string, key: string, home: string): Session {
+  const r = d.query("SELECT value FROM conversations WHERE key = ?").get(key) as { value: string } | null
+  if (!r) throw new Error(`no Amazon Q conversation for ${key} in ${path}`)
+  const state = JSON.parse(r.value) as ConversationState
+  const title = firstPrompt(state)
+  const h = header(TOOL, String(state.conversation_id), {
+    sourcePath: path,
+    ...(title ? { title } : {}),
+    project: { cwd: key, ...gitInfo(key, home) },
+  })
+  const { turns, continued } = turnsOf(state, h)
+  if (continued) h.parent = { id: continued, kind: "continued" }
+  const times = turns.map((t) => t.at).filter((t): t is string => !!t)
+  if (times[0]) h.startedAt = times[0]
+  const last = lastTime(state)
+  if (last) h.updatedAt = last
+  return { header: h, turns }
+}
+
+export const amazonQCliReader: Reader = {
+  tool: TOOL,
+  label: LABEL,
+  async list(home) {
+    const db = dbPath(home)
+    if (!exists(db)) return []
+    try {
+      return withSnapshot(db, (d) =>
+        rows(d).map(({ key, state }): SessionRef => {
+          const title = firstPrompt(state)
+          const updatedAt = lastTime(state)
+          return { tool: TOOL, sourceId: String(state.conversation_id), path: db, cwd: key, ...(title ? { title } : {}), ...(updatedAt ? { updatedAt } : {}), extra: { key } }
+        }),
+      ).sort((a, b) => (b.updatedAt ?? "").localeCompare(a.updatedAt ?? ""))
+    } catch {
+      return []
+    }
+  },
+  async read(ref, home) {
+    if (!exists(ref.path)) throw new Error(`Amazon Q database not found: ${ref.path}`)
+    const key = typeof ref.extra?.key === "string" ? ref.extra.key : ref.cwd
+    if (!key) throw new Error("this Amazon Q session reference names no folder")
+    return withSnapshot(ref.path, (d) => readQ(d, ref.path, key, home))
+  },
+}