@100xprompt/brain 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,191 @@
+import { join } from "node:path"
+import { appSupport, versionOf } from "../../fsutil.ts"
+import type { Session, ToolKind, Turn } from "../../session/types.ts"
+import { asText, clip, iso, lossCounter, noteModel, toolKindOf } from "../../session/util.ts"
+import { CONTINUED_NOTE } from "../claude-code/records.ts"
+
+// What the Amazon Q Developer CLI keeps, shared by the reader and the writer. Checked against the source of
+// aws/amazon-q-developer-cli at 1.19.7 (crates/chat-cli: database/mod.rs and sqlite_migrations/,
+// cli/chat/conversation.rs, message.rs, parser.rs, context.rs, tools/, and the resume path in cli/chat/mod.rs).
+// Catalogue: docs/sessions/2026-11-08-session-formats.md, "Amazon Q Developer CLI".
+//
+// Q keeps one conversation per folder: a row of the `conversations` table in
+// ~/Library/Application Support/amazon-q/data.sqlite3 whose key is the folder's absolute path and whose value
+// is the ConversationState as serde_json writes it. `q chat --resume` loads the row for the folder it runs
+// in, and only when its history is not empty. The history is a list of entries, each one user message and
+// the assistant's reply to it; tool calls are the reply's tool_uses, answered by the next entry's user
+// message, which carries the results instead of a prompt.
+
+export const TOOL = "amazon-q-cli"
+export const LABEL = "Amazon Q CLI"
+
+/** Q CLI versions whose conversation JSON the writer was checked against (from source). */
+export const TESTED_VERSIONS = ["1.19.7"]
+
+export const dbPath = (home: string) => join(appSupport(home), "amazon-q", "data.sqlite3")
+
+/** "1.19.7" from `qchat --version` ("qchat 1.19.7") or `q --version`; undefined when neither runs. */
+export const qVersion = (bins = ["qchat", "q"]) => {
+  for (const b of bins) {
+    const v = versionOf(b)?.match(/\d+\.\d+\.\d+/)?.[0]
+    if (v) return v
+  }
+  return undefined
+}
+
+/** The default agent, whose context manager a new conversation gets (Agent::default, ContextManager::from_agent). */
+export const DEFAULT_AGENT = "q_cli_default"
+export const DEFAULT_CONTEXT_PATHS = ["AmazonQ.md", "AGENTS.md", "README.md", ".amazonq/rules/**/*.md"]
+/** calc_max_context_files_size with no model chosen: 75% of the default 200,000-token window. */
+export const DEFAULT_CONTEXT_FILES_SIZE = 150_000
+
+/** Q's reply placeholder for a user message that has none: every history entry needs one. */
+export const NO_REPLY = "[No reply was recorded for this message before the session moved to Amazon Q.]"
+
+export type ToolUseResultBlock = { Text: string } | { Json: unknown }
+export interface ToolUseResult {
+  tool_use_id: string
+  content: ToolUseResultBlock[]
+  status: "Success" | "Error"
+}
+export type UserContent =
+  | { Prompt: { prompt: string } }
+  | { CancelledToolUses: { prompt: string | null; tool_use_results: ToolUseResult[] } }
+  | { ToolUseResults: { tool_use_results: ToolUseResult[] } }
+export interface UserMessage {
+  additional_context: string
+  env_context: { env_state: { operating_system: string | null; current_working_directory: string | null; environment_variables: unknown[] } | null }
+  content: UserContent
+  timestamp: string | null
+  images: Array<{ format: string; source: { Bytes: number[] } }> | null
+}
+export interface AssistantToolUse {
+  id: string
+  name: string
+  orig_name: string
+  args: unknown
+  orig_args: unknown
+}
+export type AssistantMessage = { Response: { message_id: string | null; content: string } } | { ToolUse: { message_id: string | null; content: string; tool_uses: AssistantToolUse[] } }
+export interface HistoryEntry {
+  user: UserMessage
+  assistant: AssistantMessage
+  request_metadata: unknown
+}
+/** ConversationState as serialized; fields this adapter does not use are left loose. */
+export interface ConversationState {
+  conversation_id: string
+  next_message: UserMessage | null
+  history: HistoryEntry[]
+  valid_history_range: [number, number]
+  transcript: string[]
+  tools: Record<string, unknown>
+  context_manager: unknown
+  context_message_length: number | null
+  latest_summary: [string, unknown] | null
+  model?: string | null
+  model_info?: { model_id?: string } | null
+  file_line_tracker?: Record<string, unknown>
+  checkpoint_manager: unknown
+  mcp_enabled?: boolean
+  [k: string]: unknown
+}
+
+/** What a Q tool does. Its built-ins are fs_read (with operations), fs_write (with a command), execute_bash. */
+export function qToolKind(name: string, args: unknown): ToolKind {
+  const a = (args && typeof args === "object" ? args : {}) as Record<string, any>
+  if (name === "fs_read") {
+    const mode = Array.isArray(a.operations) ? a.operations[0]?.mode : a.mode
+    return mode === "Directory" ? "list" : mode === "Search" ? "search" : "read"
+  }
+  if (name === "fs_write") return a.command === "create" ? "write" : "edit"
+  if (name === "execute_bash" || name === "execute_cmd") return "shell"
+  if (name === "use_aws") return "shell"
+  if (name === "todo_list") return "todo"
+  if (name === "delegate") return "task"
+  return toolKindOf(name)
+}
+
+const str = (v: unknown) => (typeof v === "string" ? v : undefined)
+
+/** A call as Q's own built-in tool would have been called, when its arguments say what that tool needs. */
+export function qCall(c: Extract<Turn, { kind: "tool_call" }>): { name: string; args: Record<string, unknown> } | undefined {
+  const i = (c.input && typeof c.input === "object" && !Array.isArray(c.input) ? c.input : {}) as Record<string, unknown>
+  const path = str(i.file_path) ?? str(i.path) ?? str(i.filePath) ?? str(i.target_file) ?? str(i.absolute_path)
+  switch (c.toolKind) {
+    case "shell": {
+      const command = str(i.command) ?? str(i.cmd) ?? (Array.isArray(i.command) ? (i.command as unknown[]).map(String).join(" ") : undefined)
+      return command ? { name: "execute_bash", args: { command } } : undefined
+    }
+    case "write": {
+      const text = str(i.content) ?? str(i.file_text) ?? str(i.contents) ?? str(i.text)
+      return path && text !== undefined ? { name: "fs_write", args: { command: "create", path, file_text: text } } : undefined
+    }
+    case "edit": {
+      const before = str(i.old_string) ?? str(i.old_str) ?? str(i.oldText) ?? str(i.oldStr)
+      const after = str(i.new_string) ?? str(i.new_str) ?? str(i.newText) ?? str(i.newStr)
+      return path && before !== undefined && after !== undefined ? { name: "fs_write", args: { command: "str_replace", path, old_str: before, new_str: after } } : undefined
+    }
+    case "read":
+      return path ? { name: "fs_read", args: { operations: [{ mode: "Line", path }] } } : undefined
+    case "list":
+      return path ? { name: "fs_read", args: { operations: [{ mode: "Directory", path }] } } : undefined
+  }
+  return undefined
+}
+
+const blockText = (b: ToolUseResultBlock) => ("Text" in b ? b.Text : asText(b.Json))
+
+/**
+ * The portable turns of a Q conversation: the summary of a compaction first (Q keeps only the summary of the
+ * turns it replaced), then the history. Returns the id of the session a brain-written conversation continues,
+ * when its note is there.
+ */
+export function turnsOf(state: ConversationState, h: Session["header"]): { turns: Turn[]; continued?: string } {
+  const turns: Turn[] = []
+  const lost = lossCounter()
+  let continued: string | undefined
+  const model = state.model_info?.model_id ?? state.model ?? undefined
+  noteModel(h, model ?? undefined)
+  if (Array.isArray(state.latest_summary) && typeof state.latest_summary[0] === "string" && state.latest_summary[0].trim())
+    turns.push({ kind: "compaction", summary: state.latest_summary[0] })
+  const results = (rs: ToolUseResult[], at?: string) => {
+    for (const r of rs) {
+      const c = clip((r.content ?? []).map(blockText).join("\n"))
+      turns.push({ kind: "tool_result", ...(at ? { at } : {}), callId: String(r.tool_use_id), ok: r.status !== "Error", output: c.text, ...(c.truncated ? { truncated: true } : {}) })
+    }
+  }
+  const prompt = (text: string | null | undefined, at?: string) => {
+    if (!text?.trim()) return
+    const note = text.match(CONTINUED_NOTE)
+    if (note) continued = note[1]
+    else turns.push({ kind: "user", ...(at ? { at } : {}), text })
+  }
+  for (const e of state.history ?? []) {
+    const u = e.user
+    const at = iso(u?.timestamp)
+    const note = u?.additional_context?.match(CONTINUED_NOTE)
+    if (note) continued = note[1]
+    if (u?.images?.length) lost.add("images", u.images.length)
+    const content = u?.content ?? ({} as UserContent)
+    if ("Prompt" in content) prompt(content.Prompt.prompt, at)
+    else if ("ToolUseResults" in content) results(content.ToolUseResults.tool_use_results ?? [], at)
+    else if ("CancelledToolUses" in content) {
+      results(content.CancelledToolUses.tool_use_results ?? [], at)
+      prompt(content.CancelledToolUses.prompt, at)
+    }
+    const a = e.assistant ?? ({} as AssistantMessage)
+    const reply = "Response" in a ? a.Response : "ToolUse" in a ? a.ToolUse : undefined
+    if (reply?.content?.trim() && reply.content !== NO_REPLY) turns.push({ kind: "assistant", text: reply.content, ...(model ? { model } : {}) })
+    if ("ToolUse" in a)
+      for (const t of a.ToolUse.tool_uses ?? []) {
+        // Q renames a call to a tool it no longer has to "dummy" when it resumes; orig_name is what was called.
+        const name = t.orig_name || t.name
+        const input = t.orig_args ?? t.args ?? {}
+        turns.push({ kind: "tool_call", id: String(t.id), name, toolKind: qToolKind(name, input), input })
+      }
+  }
+  if (state.next_message) lost.add("an unsent message")
+  lost.flush(h)
+  return { turns, ...(continued ? { continued } : {}) }
+}

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

@@ -0,0 +1,370 @@
+import { Database } from "bun:sqlite"
+import { randomUUID } from "node:crypto"
+import { copyFileSync, mkdirSync, readFileSync, realpathSync, statSync } from "node:fs"
+import { extname, join, resolve } from "node:path"
+import { toolLabel } from "../../brief.ts"
+import { exists, isDir, isRunning } from "../../fsutil.ts"
+import { withSnapshot } from "../../sqlite.ts"
+import type { Session, Turn } from "../../session/types.ts"
+import { countTurns, unpaired } from "../../session/util.ts"
+import { continuedNote } from "../claude-code/records.ts"
+import type { Readiness, WriteOptions, WriteResult, Writer } from "../types.ts"
+import { readQ } from "./reader.ts"
+import {
+  type AssistantToolUse,
+  type ConversationState,
+  DEFAULT_AGENT,
+  DEFAULT_CONTEXT_FILES_SIZE,
+  DEFAULT_CONTEXT_PATHS,
+  type HistoryEntry,
+  LABEL,
+  NO_REPLY,
+  TESTED_VERSIONS,
+  TOOL,
+  type ToolUseResult,
+  type UserMessage,
+  dbPath,
+  qCall,
+  qVersion,
+} from "./records.ts"
+
+// Continues a portable session as the Amazon Q CLI conversation of a folder: a new row of data.sqlite3's
+// `conversations` table, keyed by the folder's real path (what std::env::current_dir gives `q chat`), holding
+// the ConversationState JSON Q itself saves. History entries pair a user message with the reply: a prompt, or
+// the results of the previous reply's tool uses (both, as CancelledToolUses, when the person typed before the
+// model answered the results). Calls are mapped onto Q's built-ins (execute_bash, fs_read, fs_write) when their
+// arguments carry what those need; Q shows the model any other tool's calls under the name "dummy" when it
+// resumes. A compaction is written as /compact leaves it: its summary in latest_summary and only the turns
+// after it in the history. The note saying where the session came from is the first message's
+// additional_context, which Q sends the model with the message and never shows.
+//
+// Q keeps one conversation per folder, so this refuses a folder whose conversation has history rather than
+// replace it, writes only with Q closed, and copies the database to ~/.brain/backups/amazon-q-cli/<time>/ first.
+
+const IMAGE_FORMATS: Record<string, string> = { ".png": "Png", ".jpg": "Jpeg", ".jpeg": "Jpeg", ".gif": "Gif", ".webp": "Webp" }
+const MIME_FORMATS: Record<string, string> = { "image/png": "Png", "image/jpeg": "Jpeg", "image/gif": "Gif", "image/webp": "Webp" }
+/** MAX_IMAGE_SIZE in Q's chat consts. */
+const IMAGE_LIMIT = 10 * 1024 * 1024
+const NO_RESULT = "No result was recorded for this call; the session moved before it finished."
+
+type Call = Extract<Turn, { kind: "tool_call" }>
+type QImage = { format: string; source: { Bytes: number[] } }
+type UserDraft = { role: "user"; prompt?: string; results: ToolUseResult[]; images: QImage[]; at?: string }
+type ReplyDraft = { role: "assistant"; text: string; uses: AssistantToolUse[] }
+
+const OS = process.platform === "darwin" ? "macos" : process.platform === "win32" ? "windows" : process.platform
+/** A time as chrono serializes a DateTime<FixedOffset> at UTC: "Z", and no fraction when it is zero. */
+const qTime = (at?: string) => (at && Number.isFinite(Date.parse(at)) ? new Date(at).toISOString().replace(".000Z", "Z") : null)
+
+export interface QPlan {
+  state: ConversationState
+  lost: string[]
+  /** What a read-back must find. */
+  expect: { users: number; assistants: number; calls: number }
+}
+
+/** The ConversationState for `session` continued in `cwd` (a real path). Pure apart from reading attached images. */
+export function planQ(session: Session, opts: { cwd: string; now: Date }): QPlan {
+  const label = toolLabel(session.header.tool)
+  const drops = new Map<string, number>()
+  const drop = (what: string, n = 1) => drops.set(what, (drops.get(what) ?? 0) + n)
+  const lastCompaction = session.turns.map((t) => t.kind).lastIndexOf("compaction")
+  const summary = lastCompaction >= 0 ? (session.turns[lastCompaction] as Extract<Turn, { kind: "compaction" }>).summary : undefined
+  if (lastCompaction > 0) drop("turns before the last compaction, which Q keeps only as its summary", lastCompaction)
+  const turns = session.turns.slice(lastCompaction + 1)
+  const answered = new Set(turns.filter((t) => t.kind === "tool_result").map((t) => (t as Extract<Turn, { kind: "tool_result" }>).callId))
+
+  // Tool use ids: the service takes [A-Za-z0-9_-]; others are mapped once, the same way for call and result.
+  const ids = new Map<string, string>()
+  const used = new Set<string>()
+  let remapped = 0
+  const callId = (raw: string) => {
+    let v = ids.get(raw)
+    if (v) return v
+    const base = /^[A-Za-z0-9_-]{1,64}$/.test(raw) ? raw : `tooluse_${raw.replace(/[^A-Za-z0-9]/g, "").slice(-40) || "x"}`
+    v = base
+    for (let n = 2; used.has(v); n++) v = `${base}_${n}`
+    ids.set(raw, v)
+    used.add(v)
+    if (v !== raw) remapped++
+    return v
+  }
+
+  // Regroup the flat turns into alternating user messages and replies.
+  const msgs: Array<UserDraft | ReplyDraft> = []
+  const last = () => msgs[msgs.length - 1]
+  const userMsg = (at?: string): UserDraft => {
+    const l = last()
+    if (l?.role === "user") return l
+    const u: UserDraft = { role: "user", results: [], images: [], ...(at ? { at } : {}) }
+    msgs.push(u)
+    return u
+  }
+  const reply = (): ReplyDraft => {
+    const l = last()
+    if (l?.role === "assistant") return l
+    const a: ReplyDraft = { role: "assistant", text: "", uses: [] }
+    msgs.push(a)
+    return a
+  }
+  const result = (raw: string, ok: boolean, output: string, at?: string) =>
+    userMsg(at).results.push({ tool_use_id: callId(raw), content: [{ Text: output || "(no output)" }], status: ok ? "Success" : "Error" })
+  const written = new Set<string>()
+  const done = new Set<string>()
+  let joined = 0
+  let dummies = 0
+
+  for (const t of turns) {
+    switch (t.kind) {
+      case "user": {
+        let text = t.text
+        const u = userMsg(t.at)
+        for (const a of t.attachments ?? []) {
+          if (!a.path) continue // bytes the reader could not keep; it already counted them
+          if (a.kind === "file") {
+            text += `\n\n[Attached file: ${a.path}]`
+            continue
+          }
+          const format = (a.mime ? MIME_FORMATS[a.mime] : undefined) ?? IMAGE_FORMATS[extname(a.path).toLowerCase()]
+          let size = Number.POSITIVE_INFINITY
+          try {
+            size = statSync(a.path).size
+          } catch {}
+          if (format && size <= IMAGE_LIMIT) u.images.push({ format, source: { Bytes: [...readFileSync(a.path)] } })
+          else drop("images that could not be attached")
+        }
+        if (!text.trim()) break
+        if (u.prompt !== undefined) joined++
+        u.prompt = u.prompt === undefined ? text : `${u.prompt}\n\n${text}`
+        break
+      }
+      case "assistant": {
+        if (!t.text.trim()) break
+        const a = reply()
+        if (a.text) joined++
+        a.text = a.text ? `${a.text}\n\n${t.text}` : t.text
+        break
+      }
+      case "reasoning":
+        drop("reasoning (Q has no record for it)")
+        break
+      case "tool_call": {
+        if (written.has(t.id)) {
+          drop("repeated tool call ids")
+          break
+        }
+        written.add(t.id)
+        const mapped = qCall(t as Call)
+        const args = mapped?.args ?? (t.input && typeof t.input === "object" && !Array.isArray(t.input) ? t.input : { input: t.input ?? null })
+        if (!mapped) dummies++
+        const name = mapped?.name ?? t.name
+        reply().uses.push({ id: callId(t.id), name, orig_name: name, args, orig_args: args })
+        if (!answered.has(t.id)) {
+          result(t.id, false, NO_RESULT, t.at)
+          done.add(t.id)
+          drop("tool calls without a result (closed as errors)")
+        }
+        break
+      }
+      case "tool_result": {
+        if (!written.has(t.callId)) {
+          drop("tool results without a call")
+          break
+        }
+        if (done.has(t.callId)) {
+          drop("repeated tool results")
+          break
+        }
+        done.add(t.callId)
+        result(t.callId, t.ok, t.fullPath ? `${t.output}\n\n[Full output: ${t.fullPath}]` : t.output, t.at)
+        break
+      }
+      case "compaction":
+        break // only the last one is kept, as latest_summary
+      case "file_edit":
+        if (!t.callId || !written.has(t.callId)) drop("file edits outside a tool call")
+        break
+      case "subagent":
+        drop("subagent transcripts (their results stay in the parent's tool results)")
+        break
+    }
+  }
+
+  // Pair them into history entries; the first message carries the note.
+  const note = continuedNote(label, session.header.id, opts.now.toISOString().slice(0, 10))
+  const envContext = { env_state: { operating_system: OS, current_working_directory: opts.cwd, environment_variables: [] } }
+  const toUser = (u: UserDraft | undefined, first: boolean): UserMessage => {
+    const prompt = u?.prompt ?? (u?.results.length ? undefined : first ? note : "")
+    const content: UserMessage["content"] =
+      u?.results.length && prompt !== undefined
+        ? { CancelledToolUses: { prompt, tool_use_results: u.results } }
+        : u?.results.length
+          ? { ToolUseResults: { tool_use_results: u.results } }
+          : { Prompt: { prompt: prompt ?? "" } }
+    return {
+      additional_context: first && prompt !== note ? note : "",
+      env_context: envContext,
+      content,
+      timestamp: qTime(u?.at),
+      images: u?.images.length ? u.images : null,
+    }
+  }
+  const history: HistoryEntry[] = []
+  const transcript: string[] = []
+  let pending: UserDraft | undefined
+  let first = true
+  const entry = (u: UserDraft | undefined, a: ReplyDraft | undefined) => {
+    const user = toUser(u, first)
+    first = false
+    const content = a?.text ?? NO_REPLY
+    const assistant: HistoryEntry["assistant"] = a?.uses.length
+      ? { ToolUse: { message_id: randomUUID(), content, tool_uses: a.uses } }
+      : { Response: { message_id: randomUUID(), content } }
+    history.push({ user, assistant, request_metadata: null })
+    const c = user.content as Record<string, any>
+    const typed = c.Prompt?.prompt ?? c.CancelledToolUses?.prompt
+    if (typeof typed === "string" && typed && typed !== note) transcript.push(`> ${typed.replace(/\n/g, "> \n")}`)
+    transcript.push(`${content}\n[Tool uses: ${a?.uses.length ? a.uses.map((x) => x.name).join(",") : "none"}]`)
+  }
+  for (const m of msgs) {
+    if (m.role === "user") pending = m
+    else {
+      entry(pending, m)
+      pending = undefined
+    }
+  }
+  if (pending) entry(pending, undefined)
+
+  const nowMs = opts.now.getTime()
+  const state: ConversationState = {
+    conversation_id: randomUUID(),
+    next_message: null,
+    history,
+    valid_history_range: [0, history.length],
+    transcript,
+    tools: {},
+    context_manager: { max_context_files_size: DEFAULT_CONTEXT_FILES_SIZE, current_profile: DEFAULT_AGENT, paths: DEFAULT_CONTEXT_PATHS, hooks: {} },
+    context_message_length: null,
+    latest_summary:
+      summary !== undefined
+        ? [
+            `[Summary of the earlier conversation in ${label}, which replaced the turns before it]\n\n${summary}`,
+            {
+              request_id: null,
+              message_id: randomUUID(),
+              request_start_timestamp_ms: nowMs,
+              stream_end_timestamp_ms: nowMs,
+              time_to_first_chunk: null,
+              time_between_chunks: [],
+              user_prompt_length: 0,
+              response_size: summary.length,
+              chat_conversation_type: null,
+              tool_use_ids_and_names: [],
+              model_id: null,
+              message_meta_tags: [],
+            },
+          ]
+        : null,
+    file_line_tracker: {},
+    checkpoint_manager: null,
+    mcp_enabled: true,
+  }
+  const expect = {
+    users: msgs.filter((m) => m.role === "user" && m.prompt !== undefined).length,
+    assistants: msgs.filter((m) => m.role === "assistant" && m.text.trim()).length,
+    calls: written.size,
+  }
+  const lost = [...drops].map(([what, n]) => `${what} (${n})`)
+  if (joined) lost.push(`consecutive messages joined into one, as Q alternates them (${joined})`)
+  if (dummies) lost.push(`calls to tools Q does not have, which Q shows the model as "dummy" (${dummies})`)
+  if (remapped) lost.push(`tool call ids, remapped to ids Q accepts (${remapped})`)
+  return { state, lost, expect }
+}
+
+/** The history length of the conversation already stored for `key`, or undefined when there is none. */
+function storedHistory(d: Database, key: string): number | undefined {
+  const r = d.query("SELECT value FROM conversations WHERE key = ?").get(key) as { value: string } | null
+  if (!r) return undefined
+  try {
+    const h = (JSON.parse(r.value) as ConversationState).history
+    return Array.isArray(h) ? h.length : 0
+  } catch {
+    return 1 // unreadable: treat as a conversation, never overwrite it
+  }
+}
+
+const hasTable = (d: Database) => !!d.query("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'conversations'").get()
+const realCwd = (cwd: string) => {
+  try {
+    return realpathSync(cwd)
+  } catch {
+    return resolve(cwd)
+  }
+}
+const sh = (s: string) => (/^[\w./@%+=:,-]+$/.test(s) ? s : `'${s.replace(/'/g, `'\\''`)}'`)
+const stamp = (d: Date) => d.toISOString().replace(/[:.]/g, "-")
+
+/** The Amazon Q CLI writer; `version` and `running` are for tests, which must not depend on an installed Q. */
+export function amazonQCliWriter(opts: { version?: string; running?: () => boolean } = {}): Writer {
+  const running = opts.running ?? (() => isRunning("qchat") || isRunning("q"))
+  return {
+    tool: TOOL,
+    label: LABEL,
+    way: "native",
+
+    async ready(w: WriteOptions): Promise<Readiness> {
+      const v = opts.version ?? qVersion()
+      if (!v) return { ok: false, why: "Amazon Q CLI is not installed (neither `qchat --version` nor `q --version` ran)" }
+      if (!TESTED_VERSIONS.includes(v)) return { ok: false, why: `Amazon Q CLI ${v} is not a version this writer was checked against (${TESTED_VERSIONS.join(", ")})` }
+      if (!isDir(w.cwd)) return { ok: false, why: `the folder to continue in does not exist: ${w.cwd}` }
+      const db = dbPath(w.home)
+      if (!exists(db)) return { ok: false, why: "Amazon Q CLI has no database yet; run `q chat` once first" }
+      if (running()) return { ok: false, why: "Amazon Q CLI is running; close it first, since it writes the same database" }
+      const key = realCwd(w.cwd)
+      const n = withSnapshot(db, (d) => (hasTable(d) ? storedHistory(d, key) : -1))
+      if (n === -1) return { ok: false, why: `${db} has no conversations table; it is not a database this writer knows` }
+      if (n) return { ok: false, why: `Amazon Q keeps one conversation per folder and ${key} already has one; continue in another folder` }
+      return { ok: true }
+    },
+
+    async write(session: Session, w: WriteOptions): Promise<WriteResult> {
+      const now = new Date()
+      const key = realCwd(w.cwd)
+      const plan = planQ(session, { cwd: key, now })
+      const db = dbPath(w.home)
+      const backup = join(w.home, ".brain", "backups", TOOL, stamp(now))
+      const result = { tool: TOOL, way: "native" as const, sessionId: plan.state.conversation_id, written: [db, backup], open: `cd ${sh(key)} && q chat --resume`, lost: plan.lost }
+      if (w.dryRun) return { ...result, dryRun: true }
+
+      if (!exists(db)) throw new Error("Amazon Q CLI has no database yet; run `q chat` once first")
+      mkdirSync(backup, { recursive: true })
+      for (const side of ["", "-wal", "-shm"]) if (exists(db + side)) copyFileSync(db + side, join(backup, `data.sqlite3${side}`))
+
+      const d = new Database(db)
+      try {
+        d.exec("PRAGMA busy_timeout = 5000")
+        if (!hasTable(d)) throw new Error(`${db} has no conversations table; it is not a database this writer knows`)
+        d.transaction(() => {
+          const n = storedHistory(d, key)
+          if (n) throw new Error(`Amazon Q keeps one conversation per folder and ${key} already has one; nothing was written`)
+          // An empty conversation (what /clear leaves) is replaced, as Q replaces it on the next message.
+          d.prepare("INSERT INTO conversations (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value").run(key, JSON.stringify(plan.state))
+          // Read back as the reader reads Q; throwing here rolls the transaction back.
+          const back = readQ(d, db, key, w.home)
+          const c = countTurns(back)
+          const pairs = unpaired(back)
+          const e = plan.expect
+          if (c.user !== e.users || c.assistant !== e.assistants || c.tool_call !== e.calls || pairs.calls.length || pairs.results.length)
+            throw new Error(
+              `the Amazon Q conversation did not read back as written (users ${c.user}/${e.users}, replies ${c.assistant}/${e.assistants}, tool calls ${c.tool_call}/${e.calls}, unpaired ${pairs.calls.length + pairs.results.length}); nothing was written`,
+            )
+        })()
+      } finally {
+        d.close()
+      }
+      return { ...result, dryRun: false }
+    },
+  }
+}
+
+export const amazonQCliNativeWriter = amazonQCliWriter()

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

@@ -0,0 +1,9 @@
+import type { Reader, Writer } from "../types.ts"
+import { amazonQReader } from "./reader.ts"
+import { amazonQNativeWriter } from "./writer.ts"
+
+// Amazon Q Developer's IDE chat (VS Code-family extension and JetBrains plugin, one shared language
+// server): reads the per-workspace history databases and continues any session as a new conversation in
+// the workspace's database, opened by Amazon Q when the editor next opens the folder.
+export const readers: Reader[] = [amazonQReader]
+export const writers: Writer[] = [amazonQNativeWriter]