@100xprompt/brain 0.0.0-stage → 0.1.1

package/src/adapters/mastracode/writer.ts

@@ -0,0 +1,385 @@
+import { Database } from "bun:sqlite"
+import { randomUUID } from "node:crypto"
+import { chmodSync, copyFileSync, mkdirSync, rmSync } from "node:fs"
+import { basename, dirname, join } from "node:path"
+import { toolLabel } from "../../brief.ts"
+import { exists, isDir } from "../../fsutil.ts"
+import { imageDataUrl, parseDataUrl } from "../../session/attachments.ts"
+import { withSnapshot } from "../../sqlite.ts"
+import type { Session, Turn } from "../../session/types.ts"
+import { countTurns, unpaired } from "../../session/util.ts"
+import { continuedNote } from "../opencode/note.ts"
+import { continuedTitle, sh } from "../opencode/writer.ts"
+import type { Readiness, WriteOptions, WriteResult, Writer } from "../types.ts"
+import { readMastra } from "./reader.ts"
+import {
+  COLUMNS,
+  LABEL,
+  SCHEMA,
+  TESTED_VERSIONS,
+  TOOL,
+  type Content,
+  type MessageRow,
+  type Part,
+  type ThreadRow,
+  encodeJsonb,
+  mastraBin,
+  mastraVersion,
+  otherStore,
+  realDir,
+  resourceIdFor,
+  storeInUse,
+  storePath,
+} from "./records.ts"
+
+// Continues a portable session in MastraCode as a new thread of its store, with rows shaped like the ones the
+// 0.37.1 CLI writes (test/fixtures/native-corpus/mastracode) and the semantics of session-migrate's
+// mastracode.py (MIT): each prompt a "signal" row of type user; each reply one assistant row of type v2 with
+// all its steps (a step-start part between them), every tool call folded together with its result into one
+// tool-invocation part (state "result", or "output-error" for a failure, as MastraCode stores one); readable
+// reasoning as a reasoning part; pasted images as file parts with their base64 bytes. A compaction is a
+// tagged user row, not MastraCode's observational memory: 0.37.1 leaves historical system rows out of the
+// next request, and a user row is replayed. The note saying where the session came from is a user row too.
+//
+// The thread is scoped to the project's resource id (records.ts) so MastraCode finds it from that folder.
+// The store is SQLite that MastraCode holds open while it runs: the write needs it closed, backs the store up
+// first, and inserts in one IMMEDIATE transaction that reads the thread back before committing. A missing
+// store is created with just the two conversation tables, which MastraCode initialises its other tables around.
+
+const NO_RESULT = "No result was recorded for this call; the session moved before it finished."
+const SAFE_ID = /^[A-Za-z0-9_-]{1,64}$/
+
+export interface MastraPlan {
+  thread: ThreadRow
+  messages: MessageRow[]
+  lost: string[]
+  /** What a read-back must find. */
+  expect: { users: number; assistants: number; calls: number; reasoning: number; compactions: number }
+}
+
+/** The rows of a new MastraCode thread continuing `session`. Pure apart from reading attached images. */
+export function planMastra(session: Session, opts: { id: string; cwd: string; resourceId: string; now: Date }): MastraPlan {
+  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 turns = session.turns
+  const expect = { users: 0, assistants: 0, calls: 0, reasoning: 0, compactions: 0 }
+
+  // Times are ISO strings with milliseconds; MastraCode orders a thread's rows by them, so they only go forward.
+  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 - 10) - 1
+  const tick = (at?: string) => {
+    const t = at ? Date.parse(at) : Number.NaN
+    clock = Number.isFinite(t) && t > clock ? t : clock + 1
+    return clock
+  }
+
+  // Each call's first result, wherever it comes: MastraCode keeps the two in one part.
+  const results = new Map<string, Extract<Turn, { kind: "tool_result" }>>()
+  for (const t of turns) if (t.kind === "tool_result" && !results.has(t.callId)) results.set(t.callId, t)
+
+  // Tool call ids and names as providers take them; others are mapped once, the same way everywhere.
+  const ids = new Map<string, string>()
+  const used = new Set<string>()
+  let remapped = 0
+  const callId = (id: string) => {
+    let v = ids.get(id)
+    if (v) return v
+    const base = SAFE_ID.test(id) ? id : `call_${id.replace(/[^A-Za-z0-9]/g, "").slice(-40) || "x"}`
+    v = base
+    for (let n = 2; used.has(v); n++) v = `${base}_${n}`
+    ids.set(id, v)
+    used.add(v)
+    if (v !== id) remapped++
+    return v
+  }
+  let renamed = 0
+  const toolName = (name: string) => {
+    const v = name.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 64) || "tool"
+    if (v !== name) renamed++
+    return v
+  }
+
+  // Rows are built with numeric times, stamped at the end (when they may still shift back to now).
+  type Draft = { role: MessageRow["role"]; type: MessageRow["type"]; at: number; parts: Part[]; tag?: string; model?: string }
+  const drafts: Draft[] = []
+  const signal = (parts: Part[], at: number, tag?: string) => drafts.push({ role: "signal", type: "user", at, parts, ...(tag ? { tag } : {}) })
+
+  let model = (turns.find((t) => t.kind === "assistant" && t.model) as { model?: string } | undefined)?.model ?? session.header.models.at(-1)
+  let reply: { d: Draft; calls: number; results: boolean } | undefined
+  const closeReply = () => (reply = undefined)
+  /** The open reply, or a new one; text after a tool call, or a call after results, starts a new step in it. */
+  const replyFor = (at: number, kind: "text" | "call") => {
+    if (!reply) {
+      const d: Draft = { role: "assistant", type: "v2", at, parts: [], ...(model ? { model } : {}) }
+      drafts.push(d)
+      reply = { d, calls: 0, results: false }
+    } else if ((kind === "text" && reply.calls) || (kind === "call" && reply.results)) {
+      reply.d.parts.push({ type: "step-start", createdAt: at })
+      reply.calls = 0
+      reply.results = false
+    }
+    return reply
+  }
+
+  signal([{ type: "text", text: continuedNote(label, session.header.id, opts.now.toISOString().slice(0, 10)), createdAt: tick(turns[0]?.at) }], clock, "note")
+  const written = new Set<string>()
+  const calls = new Set(turns.filter((t) => t.kind === "tool_call").map((t) => (t as Extract<Turn, { kind: "tool_call" }>).id))
+
+  for (const t of turns) {
+    switch (t.kind) {
+      case "user": {
+        const files: Part[] = []
+        let text = t.text
+        for (const a of t.attachments ?? []) {
+          const img = a.kind === "image" ? parseDataUrl(imageDataUrl(a)) : undefined
+          if (img) files.push({ type: "file", data: img.base64, mimeType: img.mime })
+          else if (a.kind === "file" && a.path) text += `\n\n[Attached file: ${a.path}]`
+          else drop("attachments")
+        }
+        if (!text.trim() && !files.length) break
+        closeReply()
+        const at = tick(t.at)
+        signal([...(text.trim() ? [{ type: "text", text, createdAt: at }] : []), ...files.map((f) => ({ ...f, createdAt: at }))], at)
+        expect.users++
+        break
+      }
+      case "assistant": {
+        if (!t.text.trim()) break
+        // A reply belongs to one model: text from another starts a new reply.
+        if (t.model && t.model !== model) {
+          closeReply()
+          model = t.model
+        }
+        const at = tick(t.at)
+        replyFor(at, "text").d.parts.push({ type: "text", text: t.text, createdAt: at })
+        expect.assistants++
+        break
+      }
+      case "reasoning": {
+        if (!t.text.trim()) break
+        const at = tick(t.at)
+        replyFor(at, "text").d.parts.push({ type: "reasoning", reasoning: t.text, details: [{ type: "text", text: t.text }], createdAt: at })
+        expect.reasoning++
+        drop("reasoning: kept as text, without provider signatures")
+        break
+      }
+      case "tool_call": {
+        if (written.has(t.id)) {
+          drop("repeated tool call ids")
+          break
+        }
+        written.add(t.id)
+        const r = replyFor(tick(t.at), "call")
+        let args = t.input
+        if (!args || typeof args !== "object" || Array.isArray(args)) {
+          args = { input: args ?? null }
+          drop("tool inputs that were not objects, wrapped as {input}")
+        }
+        const inv: Record<string, unknown> = { toolCallId: callId(t.id), toolName: toolName(t.name), args }
+        const res = results.get(t.id)
+        if (!res) {
+          Object.assign(inv, { state: "output-error", errorText: NO_RESULT })
+          drop("calls with no result, marked as failed")
+        } else {
+          const output = res.fullPath ? `${res.output}\n\n[Full output: ${res.fullPath}]` : res.output
+          if (res.ok) Object.assign(inv, { state: "result", result: output })
+          else Object.assign(inv, { state: "output-error", errorText: output.trim() ? output : "The tool call failed." })
+        }
+        r.d.parts.push({ type: "tool-invocation", toolInvocation: inv })
+        r.calls++
+        expect.calls++
+        break
+      }
+      case "tool_result": {
+        // The result is already folded into its call; here it only marks the step as answered.
+        if (results.get(t.callId) !== t) drop("repeated tool results")
+        else if (!calls.has(t.callId)) drop("tool results without a call")
+        else if (reply?.calls) reply.results = true
+        break
+      }
+      case "compaction": {
+        closeReply()
+        const at = tick(t.at)
+        signal([{ type: "text", text: `[Summary of the earlier conversation in ${label}, which replaced the turns before it]\n\n${t.summary}`, createdAt: at }], at, "compaction")
+        expect.compactions++
+        break
+      }
+      case "file_edit":
+        if (!t.callId || !written.has(t.callId)) drop("file edits not made by a tool call")
+        break
+      case "subagent":
+        drop("subagent sessions (their call and result are kept)")
+        break
+    }
+  }
+
+  // Nothing may sort after the next row MastraCode writes, which is stamped now.
+  const late = clock - opts.now.getTime()
+  const stamp = (ms: number) => new Date(late > 0 ? ms - late : ms).toISOString()
+  const messages: MessageRow[] = drafts.map((d) => {
+    const id = randomUUID()
+    const createdAt = stamp(d.at)
+    const parts = d.parts.map((p) => (typeof p.createdAt === "number" && late > 0 ? { ...p, createdAt: p.createdAt - late } : p))
+    let content: Content
+    if (d.role === "signal") {
+      // As MastraCode records a prompt: the signal's own id and times beside the parts.
+      const metadata: Record<string, any> = { signal: { acceptedAt: createdAt, createdAt, id, tagName: "user", type: "user" } }
+      if (d.tag) metadata.brain = { kind: d.tag }
+      content = { format: 2, metadata, parts }
+    } else {
+      const last = [...parts].reverse().find((p) => p.type === "text")
+      content = { format: 2, parts, ...(last ? { content: last.text as string } : {}), ...(d.model ? { metadata: { modelId: d.model } } : {}) }
+    }
+    return { id, role: d.role, type: d.type, content, createdAt }
+  })
+
+  const lost = [...drops].map(([what, n]) => `${what} (${n})`)
+  if (remapped) lost.push(`tool call ids, remapped to ids providers accept (${remapped})`)
+  if (renamed) lost.push(`tool names changed to fit providers (${renamed})`)
+  if (session.turns.some((t) => t.kind === "assistant" && t.usage)) lost.push("token usage (MastraCode counts its own)")
+  const thread: ThreadRow = {
+    id: opts.id,
+    resourceId: opts.resourceId,
+    title: continuedTitle(session),
+    // No model: the source's model names are not MastraCode model ids, so the person's own default applies.
+    metadata: { projectPath: opts.cwd, brain: { continues: session.header.id } },
+    createdAt: messages[0]!.createdAt,
+    updatedAt: messages.at(-1)!.createdAt,
+  }
+  return { thread, messages, lost, expect }
+}
+
+/** Which tables and columns are missing from a store, for one this writer does not know. */
+function missingColumns(db: Database): string[] {
+  const missing: string[] = []
+  for (const [table, cols] of Object.entries(COLUMNS)) {
+    const have = new Set((db.query(`PRAGMA table_info("${table}")`).all() as Array<{ name: string }>).map((c) => c.name))
+    if (!have.size) missing.push(table)
+    else for (const c of cols) if (!have.has(c)) missing.push(`${table}.${c}`)
+  }
+  return missing
+}
+
+/**
+ * Inserts the plan's thread in one IMMEDIATE transaction and reads it back before committing; any mismatch, or
+ * an id the store already has, leaves the store as it was. Creates a missing store (0600, in 0700 folders).
+ */
+export function installMastra(dbPath: string, plan: MastraPlan, home: string): void {
+  const fresh = !exists(dbPath)
+  if (fresh) mkdirSync(dirname(dbPath), { recursive: true, mode: 0o700 })
+  const db = new Database(dbPath)
+  let ok = false
+  try {
+    if (fresh) {
+      chmodSync(dbPath, 0o600)
+      db.exec(SCHEMA)
+    }
+    db.exec("PRAGMA busy_timeout = 5000")
+    const missing = missingColumns(db)
+    if (missing.length) throw new Error(`the MastraCode store at ${dbPath} has no ${missing.join(", ")}; it is not a store this writer knows`)
+    const t = plan.thread
+    db.transaction(() => {
+      if (db.query("SELECT 1 FROM mastra_threads WHERE id = ?").get(t.id)) throw new Error(`the MastraCode store already has a thread ${t.id}; refusing to overwrite it`)
+      const taken = db.query("SELECT 1 FROM mastra_messages WHERE id = ?")
+      for (const m of plan.messages) if (taken.get(m.id)) throw new Error(`the MastraCode store already has a message ${m.id}; refusing to reuse it`)
+      db.prepare('INSERT INTO "mastra_threads" (id, resourceId, title, metadata, createdAt, updatedAt) VALUES (?, ?, ?, ?, ?, ?)').run(
+        t.id,
+        t.resourceId,
+        t.title,
+        encodeJsonb(t.metadata),
+        t.createdAt,
+        t.updatedAt,
+      )
+      const add = db.prepare('INSERT INTO "mastra_messages" (id, thread_id, content, role, type, createdAt, resourceId) VALUES (?, ?, ?, ?, ?, ?, ?)')
+      for (const m of plan.messages) add.run(m.id, t.id, JSON.stringify(m.content), m.role, m.type, m.createdAt, t.resourceId)
+      // Read back as the reader reads MastraCode; throwing here rolls the transaction back.
+      const back = readMastra(db, t.id, dbPath, 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.reasoning !== e.reasoning ||
+        n.compaction !== e.compactions ||
+        pairs.calls.length ||
+        pairs.results.length
+      )
+        throw new Error(
+          `the MastraCode thread did not read back as written (users ${n.user}/${e.users}, replies ${n.assistant}/${e.assistants}, tool calls ${n.tool_call}/${e.calls}, reasoning ${n.reasoning}/${e.reasoning}, summaries ${n.compaction}/${e.compactions}, unpaired ${pairs.calls.length + pairs.results.length}); nothing was kept`,
+        )
+    }).immediate()
+    ok = true
+  } finally {
+    db.close()
+    // A store this write created and could not fill is removed again, so MastraCode creates its own.
+    if (fresh && !ok) for (const side of ["", "-wal", "-shm", "-journal"]) rmSync(dbPath + side, { force: true })
+  }
+}
+
+/** Copies the store with its write-ahead log before anything is changed. */
+function backup(dbPath: string, dir: string) {
+  mkdirSync(dir, { recursive: true })
+  for (const side of ["", "-wal", "-shm"]) if (exists(dbPath + side)) copyFileSync(dbPath + side, join(dir, basename(dbPath) + side))
+}
+
+const PROMPT = "Continue where this session left off."
+
+export const mastracodeWriter: Writer = {
+  tool: TOOL,
+  label: LABEL,
+  way: "native",
+
+  async ready(opts: WriteOptions): Promise<Readiness> {
+    const bin = mastraBin()
+    if (!bin) return { ok: false, why: "MastraCode is not installed (no mastracode on PATH)" }
+    const v = mastraVersion(bin)
+    if (!v) return { ok: false, why: "`mastracode --version` did not run" }
+    if (!TESTED_VERSIONS.includes(v)) return { ok: false, why: `MastraCode ${v} is not a version this writer was checked against (${TESTED_VERSIONS.join(", ")})` }
+    if (!isDir(opts.cwd)) return { ok: false, why: `the folder to continue in does not exist: ${opts.cwd}` }
+    const db = storePath(opts.home)
+    const elsewhere = otherStore(db)
+    if (elsewhere) return { ok: false, why: `${elsewhere}; brain writes only the local store at ${db}` }
+    const busy = storeInUse(db)
+    if (busy) return { ok: false, why: busy }
+    if (exists(db)) {
+      let missing: string[]
+      try {
+        missing = withSnapshot(db, missingColumns)
+      } catch (e) {
+        return { ok: false, why: `the MastraCode store at ${db} cannot be read: ${(e as Error).message}` }
+      }
+      if (missing.length) return { ok: false, why: `the MastraCode store at ${db} has no ${missing.join(", ")}; it is not a store this writer knows` }
+    }
+    return { ok: true }
+  },
+
+  async write(session: Session, opts: WriteOptions): Promise<WriteResult> {
+    const cwd = realDir(opts.cwd)
+    const db = storePath(opts.home)
+    const now = new Date()
+    const resourceId = resourceIdFor(cwd)
+    const plan = planMastra(session, { id: randomUUID(), cwd, resourceId, now })
+    const backupDir = join(opts.home, ".brain", "backups", TOOL, now.toISOString().replace(/[:.]/g, "-"))
+    const hadStore = exists(db)
+    if (!opts.dryRun) {
+      const busy = storeInUse(db)
+      if (busy) throw new Error(busy)
+      if (hadStore) backup(db, backupDir)
+      installMastra(db, plan, opts.home)
+    }
+    const id = plan.thread.id
+    return {
+      tool: TOOL,
+      way: "native",
+      sessionId: id,
+      written: hadStore ? [db, backupDir] : [db],
+      open: `cd ${sh(cwd)} && mastracode --thread ${id} --resource-id ${sh(resourceId)} --prompt ${sh(PROMPT)}`,
+      note: `MastraCode looks a thread up by its resource id, so run it from ${cwd} with both flags; --prompt sends one headless turn on the thread.`,
+      lost: plan.lost,
+      dryRun: !!opts.dryRun,
+    }
+  },
+}

package/src/adapters/mistral-vibe/index.ts

@@ -0,0 +1,9 @@
+import type { Reader, Writer } from "../types.ts"
+import { reader } from "./reader.ts"
+import { mistralVibeImportWriter } from "./writer.ts"
+
+// Mistral Vibe: reads its session folders, and continues any session as a session folder that
+// `vibe --resume` lists and imports into Vibe's own store.
+export { reader }
+export const readers: Reader[] = [reader]
+export const writers: Writer[] = [mistralVibeImportWriter]

package/src/adapters/mistral-vibe/reader.ts

@@ -0,0 +1,62 @@
+import { join } from "node:path"
+import { exists, gitInfo, isDir, ls, mtime, readJson, readJsonl } from "../../fsutil.ts"
+import { header, lossCounter } from "../../session/util.ts"
+import type { Reader, SessionRef } from "../types.ts"
+import { LABEL, MESSAGES, META, messagesToTurns, metaTime, TOOL } from "./records.ts"
+
+// Mistral Vibe's session folders, $VIBE_HOME/logs/session/session_*/ (records.ts). Sessions Vibe 3.x keeps
+// only in its private Unified store are not read: that store is runtime-private (ADR 0006) and has no
+// published format.
+
+type Meta = Record<string, any>
+const str = (v: unknown) => (typeof v === "string" && v.trim() ? v : undefined)
+
+export const reader: Reader = {
+  tool: TOOL,
+  label: LABEL,
+
+  async list(home) {
+    const root = join(home, ".vibe", "logs", "session")
+    const refs: SessionRef[] = []
+    for (const name of ls(root)) {
+      const dir = join(root, name)
+      if (!name.startsWith("session_") || !isDir(dir) || !exists(join(dir, MESSAGES))) continue
+      const meta = readJson<Meta>(join(dir, META))
+      const sourceId = str(meta?.session_id)
+      if (!sourceId || meta?.total_messages === 0) continue
+      const title = str(meta?.title)
+      const cwd = str(meta?.environment?.working_directory)
+      const updatedAt = metaTime(meta?.end_time) ?? metaTime(meta?.start_time) ?? mtime(join(dir, MESSAGES))
+      refs.push({ tool: TOOL, sourceId, path: join(dir, MESSAGES), ...(title ? { title } : {}), ...(cwd ? { cwd } : {}), ...(updatedAt ? { updatedAt } : {}), extra: { dir } })
+    }
+    return refs.sort((a, b) => (b.updatedAt ?? "").localeCompare(a.updatedAt ?? ""))
+  },
+
+  async read(ref, home) {
+    if (!exists(ref.path)) throw new Error(`${ref.path} does not exist`)
+    const dir = typeof ref.extra?.dir === "string" ? ref.extra.dir : join(ref.path, "..")
+    const meta = readJson<Meta>(join(dir, META))
+    const { rows, bad } = readJsonl(ref.path)
+    if (!rows.length) throw new Error(`${ref.path} has no Mistral Vibe messages`)
+    const lost = lossCounter()
+    if (bad) lost.add("unreadable lines", bad)
+    const cwd = str(meta?.environment?.working_directory) ?? ref.cwd
+    const title = str(meta?.title)
+    const startedAt = metaTime(meta?.start_time)
+    const updatedAt = metaTime(meta?.end_time) ?? mtime(ref.path)
+    const model = str(meta?.config?.model_name) ?? str(meta?.config?.active_model)
+    const h = header(TOOL, str(meta?.session_id) ?? ref.sourceId, {
+      sourcePath: ref.path,
+      ...(title ? { title } : {}),
+      project: { ...(cwd ? { cwd } : {}), ...gitInfo(cwd, home), ...(str(meta?.git_branch) ? { gitBranch: meta!.git_branch } : {}), ...(str(meta?.git_commit) ? { gitCommit: meta!.git_commit } : {}) },
+      ...(startedAt ? { startedAt } : {}),
+      ...(updatedAt ? { updatedAt } : {}),
+      ...(model ? { models: [model] } : {}),
+    })
+    const turns = messagesToTurns(rows, h, lost, dir)
+    const children = Array.isArray(meta?.child_sessions) ? meta!.child_sessions.length : 0
+    if (children) lost.add("subagent sessions (their results stay in the parent's tool results)", children)
+    lost.flush(h)
+    return { header: h, turns }
+  },
+}

package/src/adapters/mistral-vibe/records.ts

@@ -0,0 +1,104 @@
+import { existsSync } from "node:fs"
+import { isAbsolute, join } from "node:path"
+import type { Attachment, SessionHeader, Turn } from "../../session/types.ts"
+import { clip, iso, toolKindOf, type lossCounter } from "../../session/util.ts"
+
+// Facts about Mistral Vibe's session folders, shared by its reader and writer. They come from Vibe 3.1.0's
+// source (mistralai/mistral-vibe: vibe/core/session/session_loader.py and session_index.py, which list and
+// load them; vibe/core/session/session_interop.py and vibe/app_server/_legacy_import.py, which import one
+// into the Unified store on resume; vibe/core/types.py for LLMMessage and SessionMetadata).
+//
+// A session folder is $VIBE_HOME/logs/session/session_<YYYYmmdd_HHMMSS>_<id[:8]>/ (VIBE_HOME defaults to
+// ~/.vibe) with meta.json (session id, times, working directory, title) and messages.jsonl, one LLMMessage
+// per line in OpenAI shape: role, content, reasoning_content, tool_calls[{id, function: {name, arguments}}],
+// tool_call_id, name. A failed tool result is wrapped in <tool_error>…</tool_error>. Vibe 2.x wrote these;
+// Vibe 3.x keeps sessions in a private Unified store, still lists these folders in its resume picker, and
+// imports one into a new Unified session when it is resumed.
+
+export const TOOL = "mistral-vibe"
+export const LABEL = "Mistral Vibe"
+
+export const META = "meta.json"
+export const MESSAGES = "messages.jsonl"
+
+type Lost = ReturnType<typeof lossCounter>
+type Json = Record<string, any>
+const isObj = (v: unknown): v is Json => typeof v === "object" && v !== null && !Array.isArray(v)
+
+/** Vibe's tags around a tool result that did not succeed (vibe/core/utils/tags.py). */
+const FAILED = /^\s*<(tool_error|user_cancellation)>([\s\S]*?)<\/\1>\s*$/
+
+/** Content as Vibe stores it: a string, or a list of {type: "text", text} parts. */
+export function contentText(v: unknown): string {
+  if (typeof v === "string") return v
+  if (Array.isArray(v)) return v.map((p) => (isObj(p) && typeof p.text === "string" ? p.text : "")).join("\n")
+  return ""
+}
+
+function parseArgs(a: unknown): unknown {
+  if (typeof a !== "string") return a ?? {}
+  try {
+    return JSON.parse(a)
+  } catch {
+    return { arguments: a }
+  }
+}
+
+/** The turns of a messages.jsonl, in order. Injected context is skipped; a compaction boundary is a compaction. */
+export function messagesToTurns(rows: Json[], h: SessionHeader, lost: Lost, dir?: string): Turn[] {
+  const turns: Turn[] = []
+  const calls = new Set<string>()
+  const answered = new Set<string>()
+  for (const m of rows) {
+    if (!isObj(m)) continue
+    const text = contentText(m.content)
+    if (m.role === "user") {
+      if (m.context_boundary === "compaction") {
+        if (text.trim()) turns.push({ kind: "compaction", summary: text })
+        continue
+      }
+      if (m.injected === true) continue
+      // Vibe 2.24.3 snapshots an @mentioned image into <session>/attachments/ and records {source: {kind: "file", path}, alias, mime_type}.
+      const attachments: Attachment[] = []
+      for (const im of Array.isArray(m.images) ? m.images : []) {
+        const path = isObj(im) && isObj(im.source) && im.source.kind === "file" && typeof im.source.path === "string" ? (isAbsolute(im.source.path) ? im.source.path : dir ? join(dir, im.source.path) : undefined) : undefined
+        if (path && existsSync(path)) attachments.push({ kind: "image", path, ...(isObj(im) && typeof im.alias === "string" ? { name: im.alias } : {}), ...(isObj(im) && typeof im.mime_type === "string" ? { mime: im.mime_type } : {}) })
+        else lost.add("images")
+      }
+      if (text.trim() || attachments.length) turns.push({ kind: "user", text, ...(attachments.length ? { attachments } : {}) })
+    } else if (m.role === "assistant") {
+      const reasoning = contentText(m.reasoning_content)
+      if (reasoning.trim()) turns.push({ kind: "reasoning", text: reasoning })
+      if (Array.isArray(m.reasoning_payloads) && m.reasoning_payloads.length) lost.add("signed or encrypted reasoning")
+      if (text.trim()) turns.push({ kind: "assistant", text })
+      for (const c of Array.isArray(m.tool_calls) ? m.tool_calls : []) {
+        if (!isObj(c) || typeof c.id !== "string" || !c.id || calls.has(c.id)) continue
+        const fn = isObj(c.function) ? c.function : {}
+        const name = typeof fn.name === "string" && fn.name ? fn.name : "unknown"
+        calls.add(c.id)
+        turns.push({ kind: "tool_call", id: c.id, name, toolKind: toolKindOf(name), input: parseArgs(fn.arguments) })
+      }
+    } else if (m.role === "tool" && typeof m.tool_call_id === "string") {
+      if (!calls.has(m.tool_call_id) || answered.has(m.tool_call_id)) continue
+      answered.add(m.tool_call_id)
+      const failed = text.match(FAILED)
+      const c = clip(failed ? failed[2]! : text)
+      turns.push({ kind: "tool_result", callId: m.tool_call_id, ok: !failed && m.tool_result?.cancelled !== true, output: c.text, ...(c.truncated ? { truncated: true } : {}) })
+    }
+  }
+  // Calls never answered get a result saying so, right after the call, so every call stays paired.
+  const open = [...calls].filter((id) => !answered.has(id))
+  if (open.length) lost.add("tool results not recorded", open.length)
+  for (const id of open) {
+    const i = turns.findIndex((t) => t.kind === "tool_call" && t.id === id)
+    turns.splice(i + 1, 0, { kind: "tool_result", callId: id, ok: false, output: "(no result recorded)" })
+  }
+  if (!h.title) {
+    const first = turns.find((t) => t.kind === "user")
+    if (first?.kind === "user") h.title = first.text.replace(/\s+/g, " ").trim().slice(0, 120) || undefined
+  }
+  return turns
+}
+
+/** A meta.json time as ISO, when it parses. */
+export const metaTime = (v: unknown) => iso(v)