@100xprompt/brain 0.0.0-stage → 0.1.0

package/src/adapters/mastracode/reader.ts

@@ -0,0 +1,323 @@
+import type { Database } from "bun:sqlite"
+import { exists, gitInfo } from "../../fsutil.ts"
+import { keepImage, parseDataUrl } from "../../session/attachments.ts"
+import { withSnapshot } from "../../sqlite.ts"
+import type { Attachment, Session, Turn } from "../../session/types.ts"
+import { asText, clip, header, iso, lossCounter, noteModel } from "../../session/util.ts"
+import { CONTINUED_NOTE } from "../opencode/note.ts"
+import type { Reader, SessionRef } from "../types.ts"
+import { LABEL, TOOL, mastraToolKind, metadataOf, storePaths, type Part } from "./records.ts"
+
+// Reads MastraCode threads from its one store (records.ts), always from a copy taken with its write-ahead
+// log, so a running MastraCode is never disturbed and the newest committed turns are included.
+// Semantics ported from session-migrate's mastracode.py (MIT): a "signal" row of type user is the person's
+// prompt; an assistant row holds every step of a reply, with each tool call and its result folded into one
+// tool-invocation part (unfolded here into a call and a result); readable reasoning is kept; image file parts
+// become attachments; the thread's active observational memory is its compaction. MastraCode's runtime parts
+// (workspace and sandbox metadata) are counted as lost; step boundaries are structure, not content.
+
+/** The stores on this machine: the platform's path, and the others when present (a home copied between systems). */
+const stores = (home: string) => [...new Set(Object.values(storePaths(home)))].filter(exists)
+
+export function listThreads(d: Database, path: string): SessionRef[] {
+  const rows = d
+    .query(
+      `SELECT t.id, t.resourceId, t.title, t.metadata, t.updatedAt FROM mastra_threads t
+       WHERE EXISTS (SELECT 1 FROM mastra_messages m WHERE m.thread_id = t.id)`,
+    )
+    .all() as Array<Record<string, any>>
+  return rows.map((r) => {
+    const cwd = metadataOf(r.metadata).projectPath
+    const updatedAt = iso(r.updatedAt)
+    return {
+      tool: TOOL,
+      sourceId: String(r.id),
+      path,
+      ...(r.title ? { title: String(r.title) } : {}),
+      ...(typeof cwd === "string" && cwd ? { cwd } : {}),
+      ...(updatedAt ? { updatedAt } : {}),
+      extra: { resourceId: String(r.resourceId ?? "") },
+    }
+  })
+}
+
+export const mastracodeReader: Reader = {
+  tool: TOOL,
+  label: LABEL,
+  async list(home) {
+    const refs: SessionRef[] = []
+    for (const db of stores(home)) {
+      try {
+        refs.push(...withSnapshot(db, (d) => listThreads(d, db)))
+      } catch {
+        // A store that cannot be copied or opened lists nothing; read() says why for a thread in it.
+      }
+    }
+    return refs.sort((a, b) => (b.updatedAt ?? "").localeCompare(a.updatedAt ?? ""))
+  },
+  async read(ref, home) {
+    if (!exists(ref.path)) throw new Error(`MastraCode store not found: ${ref.path}`)
+    return withSnapshot(ref.path, (d) => readMastra(d, ref.sourceId, ref.path, home))
+  },
+}
+
+const json = (v: unknown): any => {
+  try {
+    return JSON.parse(v instanceof Uint8Array ? new TextDecoder().decode(v) : String(v))
+  } catch {
+    return undefined
+  }
+}
+
+/** The prefix brain's writer puts before a compaction summary it stores as a user row. */
+export const SUMMARY_PREFIX = /^\[Summary of the earlier conversation in [^\]\n]*\]\n\n/
+
+/** A tool result's text: strings as they are, text blocks joined (MCP and AI SDK shapes), else JSON. */
+function resultText(v: unknown): { text: string; images: number } {
+  if (typeof v === "string") return { text: v, images: 0 }
+  const blocks = Array.isArray(v) ? v : v && typeof v === "object" && Array.isArray((v as any).content) ? (v as any).content : undefined
+  // session-migrate's wrapper for a result whose text and structured content differ.
+  if (v && typeof v === "object" && (v as any).schema === "session-migrate.mastracode-tool-result.v1" && typeof (v as any).text === "string") return { text: (v as any).text, images: 0 }
+  if (v && typeof v === "object" && !Array.isArray(v) && (v as any).type === "text" && typeof (v as any).value === "string") return { text: (v as any).value, images: 0 }
+  if (!blocks) return { text: asText(v), images: 0 }
+  const parts: string[] = []
+  let images = 0
+  for (const b of blocks as any[]) {
+    if (typeof b === "string") parts.push(b)
+    else if (typeof b?.text === "string") parts.push(b.text)
+    else if (b?.type === "image" || b?.type === "media") images++
+    else parts.push(asText(b))
+  }
+  return { text: parts.join("\n"), images }
+}
+
+const resultFailed = (v: unknown) => !!v && typeof v === "object" && !Array.isArray(v) && (v as any).isError === true
+
+/** One thread from an open MastraCode store. */
+export function readMastra(d: Database, id: string, path: string, home: string): Session {
+  const thread = d.query("SELECT id, resourceId, title, metadata, createdAt, updatedAt FROM mastra_threads WHERE id = ?").get(id) as Record<string, any> | null
+  if (!thread) throw new Error(`no MastraCode thread ${id} in ${path}`)
+  const meta = metadataOf(thread.metadata)
+  const cwd = typeof meta.projectPath === "string" && meta.projectPath ? (meta.projectPath as string) : undefined
+  const h = header(TOOL, id, {
+    sourcePath: path,
+    ...(thread.title ? { title: String(thread.title) } : {}),
+    project: cwd ? { cwd, ...gitInfo(cwd, home) } : {},
+    ...(iso(thread.createdAt) ? { startedAt: iso(thread.createdAt)! } : {}),
+    ...(iso(thread.updatedAt) ? { updatedAt: iso(thread.updatedAt)! } : {}),
+  })
+  if (typeof meta.brain?.continues === "string") h.parent = { id: meta.brain.continues, kind: "continued" }
+  const threadModel = typeof meta.currentModelId === "string" && meta.currentModelId ? (meta.currentModelId as string) : undefined
+  const lost = lossCounter()
+  const turns: Turn[] = []
+  const callIds = new Set<string>()
+
+  // The thread's observational memory, MastraCode's own compaction: what it currently uses in place of older turns.
+  try {
+    const om = d.query("SELECT activeObservations FROM mastra_observational_memory WHERE threadId = ? ORDER BY updatedAt DESC LIMIT 1").get(id) as { activeObservations?: unknown } | null
+    const summary = typeof om?.activeObservations === "string" ? om.activeObservations.trim() : ""
+    if (summary) turns.push({ kind: "compaction", ...(h.startedAt ? { at: h.startedAt } : {}), summary })
+  } catch {
+    // No observational memory table (it is created when MastraCode first observes) or another layout.
+  }
+
+  const rows = d.query("SELECT id, content, role, type, createdAt FROM mastra_messages WHERE thread_id = ? ORDER BY createdAt, id").all(id) as Array<Record<string, any>>
+  for (const row of rows) {
+    const rowAt = iso(row.createdAt)
+    let content = json(row.content)
+    // Older Mastra rows hold the message's content directly: a string, or a list of AI SDK content parts.
+    if (typeof content === "string") content = { format: 2, parts: [{ type: "text", text: content }] }
+    else if (Array.isArray(content)) content = { format: 2, parts: content }
+    if (!content || typeof content !== "object" || !Array.isArray(content.parts)) {
+      lost.add("unreadable messages")
+      continue
+    }
+    const cmeta = (content.metadata && typeof content.metadata === "object" ? content.metadata : {}) as Record<string, any>
+    if (row.id === "om-continuation" || cmeta.sessionMigrate?.internal === true) {
+      lost.add("observational-memory continuation messages")
+      continue
+    }
+    const role = String(row.role)
+    if (role === "system") {
+      lost.add("system messages")
+      continue
+    }
+    if (role === "signal") {
+      const kind = String(cmeta.signal?.type ?? row.type ?? "")
+      if (kind !== "user") {
+        lost.add(`signals the tool injected (${kind || "untyped"})`)
+        continue
+      }
+    } else if (role !== "user" && role !== "assistant" && role !== "tool") {
+      lost.add(`unknown message roles: ${role}`)
+      continue
+    }
+    const parts = content.parts as Part[]
+    const textOf = (p: Part) => (typeof p.text === "string" ? p.text : "")
+
+    // A compaction summary stored as a tagged user row (by brain, or by session-migrate).
+    if (cmeta.brain?.kind === "compaction" || cmeta.sessionMigrate?.kind === "compaction") {
+      const summary = parts.filter((p) => p?.type === "text").map(textOf).join("\n\n").replace(SUMMARY_PREFIX, "")
+      if (summary.trim()) turns.push({ kind: "compaction", ...(rowAt ? { at: rowAt } : {}), summary })
+      continue
+    }
+
+    const user = role === "user" || role === "signal"
+    const model =
+      (typeof cmeta.modelId === "string" && cmeta.modelId) ||
+      (parts.find((p) => p?.type === "step-start" && typeof p.model === "string")?.model as string | undefined) ||
+      (user ? undefined : threadModel) ||
+      undefined
+    // A part's own time when it has one (tool invocations have none: they take the time of the part before).
+    let lastAt = rowAt
+    const stampOf = (p: Part) => {
+      const at = typeof p.createdAt === "number" ? iso(p.createdAt) : undefined
+      if (at) lastAt = at
+      return lastAt
+    }
+
+    // The person's prompt: its texts joined, with the images pasted into it.
+    let userText: string[] = []
+    let attachments: Attachment[] = []
+    let userAt: string | undefined
+    const flushUser = () => {
+      const text = userText.join("\n\n")
+      const note = text.match(CONTINUED_NOTE)
+      if (note) h.parent ??= { id: note[1]!, kind: "continued" }
+      else if (text.trim() || attachments.length) turns.push({ kind: "user", ...(userAt ? { at: userAt } : {}), text, ...(attachments.length ? { attachments } : {}) })
+      userText = []
+      attachments = []
+      userAt = undefined
+    }
+
+    const call = (p: Part, callId: string, name: string, input: unknown) => {
+      let cid = callId
+      for (let n = 2; callIds.has(cid); n++) cid = `${callId}#${n}`
+      callIds.add(cid)
+      const at = stampOf(p)
+      turns.push({ kind: "tool_call", ...(at ? { at } : {}), id: cid, name, toolKind: mastraToolKind(name), input: input && typeof input === "object" ? input : {} })
+      return cid
+    }
+    const result = (p: Part, callId: string, ok: boolean, value: unknown) => {
+      const { text, images } = resultText(value)
+      if (images) lost.add("images in tool results", images)
+      const out = clip(text)
+      const at = stampOf(p)
+      turns.push({ kind: "tool_result", ...(at ? { at } : {}), callId, ok, output: out.text, ...(out.truncated ? { truncated: true } : {}) })
+    }
+
+    for (const p of parts) {
+      const type = String(p?.type ?? "")
+      if (type === "text") {
+        const text = textOf(p)
+        if (user) {
+          userAt ??= stampOf(p)
+          userText.push(text)
+        } else if (text.trim()) {
+          noteModel(h, model)
+          const at = stampOf(p)
+          turns.push({ kind: "assistant", ...(at ? { at } : {}), text, ...(model ? { model } : {}) })
+        }
+        continue
+      }
+      if (type === "file" || type === "image") {
+        const mime = String(p.mimeType ?? p.mediaType ?? "")
+        const raw = type === "image" ? p.image : (p.data ?? p.url)
+        const data = typeof raw === "string" ? (parseDataUrl(raw)?.base64 ?? (raw.startsWith("data:") || /^https?:/.test(raw) ? undefined : raw)) : undefined
+        if (!mime.startsWith("image/")) {
+          lost.add("file attachments")
+          continue
+        }
+        const kept = data ? keepImage(data, mime) : undefined
+        if (!kept) lost.add("images")
+        else if (!user) lost.add("images in replies")
+        else {
+          userAt ??= stampOf(p)
+          attachments.push(kept)
+        }
+        continue
+      }
+      if (type === "data-user-message" && p.data && typeof p.data === "object") {
+        const text = typeof p.data.message === "string" ? p.data.message : typeof p.data.content === "string" ? p.data.content : ""
+        if (text) {
+          if (!user) flushUser()
+          userAt ??= stampOf(p)
+          userText.push(text)
+          if (!user) flushUser()
+          continue
+        }
+      }
+      if (type === "reasoning") {
+        const details = Array.isArray(p.details) ? (p.details as any[]) : []
+        const text =
+          (typeof p.reasoning === "string" && p.reasoning) ||
+          (typeof p.text === "string" && p.text) ||
+          details
+            .filter((x) => x?.type === "text" && typeof x.text === "string")
+            .map((x) => x.text as string)
+            .join("\n\n")
+        const signed = details.some((x) => x?.signature) || /signature|encrypted/i.test(JSON.stringify(p.providerMetadata ?? {}))
+        if (text.trim()) {
+          const at = stampOf(p)
+          turns.push({ kind: "reasoning", ...(at ? { at } : {}), text })
+          if (signed) lost.add("reasoning signatures")
+        } else if (details.some((x) => x?.type === "redacted")) lost.add("redacted reasoning")
+        else if (signed) lost.add("signed reasoning")
+        continue
+      }
+      // A tool call with its result folded in (AI SDK v4 UI part), as MastraCode stores it.
+      if (type === "tool-invocation" && p.toolInvocation && typeof p.toolInvocation === "object") {
+        const inv = p.toolInvocation as Record<string, any>
+        const name = typeof inv.toolName === "string" && inv.toolName ? inv.toolName : "unknown"
+        if (typeof inv.toolCallId !== "string" || !inv.toolCallId) {
+          lost.add("tool calls without an id")
+          continue
+        }
+        if (user) flushUser()
+        const cid = call(p, inv.toolCallId, name, inv.args)
+        if (inv.state === "result" && "result" in inv) result(p, cid, inv.isError !== true && !resultFailed(inv.result), inv.result)
+        else if (inv.state === "output-error") result(p, cid, false, typeof inv.errorText === "string" ? inv.errorText : asText(inv.errorText))
+        continue
+      }
+      // AI SDK v5 tool parts ("tool-<name>", "dynamic-tool") and model-message tool-call / tool-result parts.
+      if ((type.startsWith("tool-") && typeof p.toolCallId === "string" && type !== "tool-result" && type !== "tool-call") || type === "dynamic-tool") {
+        const name = type === "dynamic-tool" ? String(p.toolName ?? "unknown") : type.slice(5)
+        if (user) flushUser()
+        const cid = call(p, String(p.toolCallId), name, p.input)
+        if (p.state === "output-available") result(p, cid, !resultFailed(p.output), p.output)
+        else if (p.state === "output-error") result(p, cid, false, typeof p.errorText === "string" ? p.errorText : asText(p.errorText))
+        continue
+      }
+      if (type === "tool-call" && typeof p.toolCallId === "string") {
+        if (user) flushUser()
+        call(p, p.toolCallId, String(p.toolName ?? "unknown"), p.args ?? p.input)
+        continue
+      }
+      if (type === "tool-result" && typeof p.toolCallId === "string") {
+        if (user) flushUser()
+        const value = "result" in p ? p.result : p.output
+        result(p, p.toolCallId, p.isError !== true && !resultFailed(value), value)
+        continue
+      }
+      // Step boundaries carry the model, which is already read; no content.
+      if (type === "step-start") continue
+      if (type.startsWith("data-")) {
+        lost.add(`runtime parts: ${type}`)
+        continue
+      }
+      if (type === "source" || type === "source-url" || type === "source-document") {
+        lost.add("cited sources")
+        continue
+      }
+      lost.add(`unknown part types: ${type || "untyped"}`)
+    }
+    if (user) flushUser()
+    else if (!parts.some((p) => p?.type === "text") && typeof content.content === "string" && content.content.trim()) {
+      // A reply that kept its text only beside the parts.
+      noteModel(h, model)
+      turns.push({ kind: "assistant", ...(rowAt ? { at: rowAt } : {}), text: content.content, ...(model ? { model } : {}) })
+    }
+  }
+  lost.flush(h)
+  return { header: h, turns }
+}

package/src/adapters/mastracode/records.ts

@@ -0,0 +1,336 @@
+import { createHash } from "node:crypto"
+import { readFileSync, realpathSync } from "node:fs"
+import { basename, dirname, join, resolve } from "node:path"
+import { appSupport, exists, isDir, isRunning, readJson, versionOf } from "../../fsutil.ts"
+import type { ToolKind } from "../../session/types.ts"
+import { toolKindOf } from "../../session/util.ts"
+
+// Mastra Code (the `mastracode` CLI, npm `mastracode`): where its store is and what its rows look like.
+// Ported from session-migrate (xhluca/session-migrate, MIT licence): docs/mastracode-format.md and
+// src/session_migrate/formats/mastracode.py, which were checked against mastracode@0.37.1 (source commit
+// 003e7574, @mastra/core 1.63.2, @mastra/libsql 1.22.2, @mastra/memory 1.28.1), and against the store the
+// exact 0.37.1 CLI wrote in test/fixtures/native-corpus/mastracode.
+//
+// Every local conversation lives in one LibSQL (SQLite) file, mastra.db: a thread is a mastra_threads row
+// (id a UUID, resourceId the project identity it is scoped to, title, metadata as SQLite JSONB holding
+// projectPath and the thread's model), a message a mastra_messages row whose content is JSON
+// {format: 2, parts: [...]}: AI SDK UI parts (text, reasoning, tool-invocation with the call and its result
+// folded together, file) plus MastraCode's own runtime parts (step-start, data-*). What the person typed is a
+// "signal" row of type "user"; the model's reply to one prompt, every step of it, is one "assistant" row of
+// type "v2". Observational memory (its own compaction) is in mastra_observational_memory.
+//
+// Only the local file store is read and written. MastraCode can also use a remote LibSQL (MASTRA_DB_URL) or
+// PostgreSQL store; those are never touched. The path overrides MASTRA_DB_PATH, MASTRA_APP_DATA_DIR and
+// XDG_DATA_HOME are not followed (no other adapter follows its tool's overrides); the writer refuses when one
+// would make MastraCode read another store than the one written.
+
+export const TOOL = "mastracode"
+export const LABEL = "Mastra Code"
+export const TESTED_VERSIONS = ["0.37.1"]
+
+/** The store on each platform, as MastraCode's app-data path puts it (without the env overrides). */
+export const storePaths = (home: string) => ({
+  darwin: join(appSupport(home), "mastracode", "mastra.db"),
+  linux: join(home, ".local", "share", "mastracode", "mastra.db"),
+  win32: join(home, "AppData", "Roaming", "mastracode", "mastra.db"),
+})
+
+/** The store MastraCode uses on this platform. */
+export function storePath(home: string, platform: string = process.platform): string {
+  const p = storePaths(home)
+  return platform === "darwin" ? p.darwin : platform === "win32" ? p.win32 : p.linux
+}
+
+/** The schema a 0.37.1 store's two conversation tables have (MastraCode creates the rest itself on launch). */
+export const SCHEMA = `
+CREATE TABLE IF NOT EXISTS "mastra_threads" ("id" TEXT NOT NULL PRIMARY KEY,"resourceId" TEXT NOT NULL,"title" TEXT NOT NULL,"metadata" TEXT,"createdAt" TEXT NOT NULL,"updatedAt" TEXT NOT NULL);
+CREATE TABLE IF NOT EXISTS "mastra_messages" ("id" TEXT NOT NULL PRIMARY KEY,"thread_id" TEXT NOT NULL,"content" TEXT NOT NULL,"role" TEXT NOT NULL,"type" TEXT NOT NULL,"createdAt" TEXT NOT NULL,"resourceId" TEXT);
+CREATE INDEX IF NOT EXISTS "mastra_messages_thread_created" ON "mastra_messages"("thread_id","createdAt","id");
+`
+
+export const COLUMNS = {
+  mastra_threads: ["id", "resourceId", "title", "metadata", "createdAt", "updatedAt"],
+  mastra_messages: ["id", "thread_id", "content", "role", "type", "createdAt", "resourceId"],
+}
+
+/** One message part as stored (AI SDK UI parts and MastraCode's own). */
+export type Part = { type: string; [k: string]: any }
+
+/** A mastra_messages row's content. */
+export interface Content {
+  format: 2
+  parts: Part[]
+  /** The reply's text, beside its parts (assistant rows). */
+  content?: string
+  metadata?: Record<string, any>
+}
+
+/** A mastra_messages row before it is inserted. */
+export interface MessageRow {
+  id: string
+  role: "signal" | "user" | "assistant"
+  type: "user" | "v2"
+  content: Content
+  createdAt: string
+}
+
+export interface ThreadRow {
+  id: string
+  resourceId: string
+  title: string
+  metadata: Record<string, unknown>
+  createdAt: string
+  updatedAt: string
+}
+
+/** What a MastraCode tool does: execute_command is the shell, view reads a file, and so on. */
+export function mastraToolKind(name: string): ToolKind {
+  const short = name.replace(/^mastra_workspace_/, "")
+  if (short === "view") return "read"
+  if (short === "execute_command") return "shell"
+  return toolKindOf(short)
+}
+
+// --- SQLite JSONB --------------------------------------------------------------------------------------
+// mastra_threads.metadata is SQLite's binary JSON, not JSON text. A small codec, so neither reading nor
+// writing needs SQLite 3.45's json functions. Each element: a header byte (low nibble the type, high nibble
+// the payload size, or 12-15 for a 1/2/4/8-byte big-endian size after it), then the payload.
+
+const utf8 = new TextDecoder("utf-8", { fatal: true })
+const bytes = (s: string) => new TextEncoder().encode(s)
+
+/** The value a JSONB blob holds; throws when it is not well-formed JSONB. */
+export function decodeJsonb(b: Uint8Array): unknown {
+  const [v, end] = jsonbElement(b, 0, 0)
+  if (end !== b.length) throw new Error("trailing bytes after the JSONB value")
+  return v
+}
+
+function jsonbElement(b: Uint8Array, at: number, depth: number): [unknown, number] {
+  if (depth > 96 || at >= b.length) throw new Error("malformed JSONB")
+  const code = b[at]! >> 4
+  const type = b[at]! & 0x0f
+  let size = code
+  let head = 1
+  if (code >= 12) {
+    const n = [1, 2, 4, 8][code - 12]!
+    if (at + 1 + n > b.length) throw new Error("truncated JSONB header")
+    size = 0
+    for (let i = 0; i < n; i++) size = size * 256 + b[at + 1 + i]!
+    head = 1 + n
+  }
+  const start = at + head
+  const end = start + size
+  if (end > b.length) throw new Error("truncated JSONB payload")
+  const text = () => utf8.decode(b.subarray(start, end))
+  switch (type) {
+    case 0:
+      return [null, end]
+    case 1:
+      return [true, end]
+    case 2:
+      return [false, end]
+    case 3: // INT
+    case 5: // FLOAT
+    case 6: // FLOAT5
+      return [Number(text()), end]
+    case 4: {
+      // INT5: JSON5 integers, hex included
+      const t = text()
+      const neg = t.startsWith("-")
+      const n = Number(t.replace(/^[+-]/, ""))
+      return [neg ? -n : n, end]
+    }
+    case 7: // TEXT: nothing to unescape
+    case 10: // TEXTRAW
+      return [text(), end]
+    case 8: // TEXTJ: JSON escapes
+    case 9: {
+      // TEXT5: JSON5 escapes, read as JSON when they are
+      const t = text()
+      try {
+        return [JSON.parse(`"${t}"`), end]
+      } catch {
+        return [t, end]
+      }
+    }
+    case 11: {
+      const out: unknown[] = []
+      let p = start
+      while (p < end) {
+        const [v, next] = jsonbElement(b, p, depth + 1)
+        out.push(v)
+        p = next
+      }
+      if (p !== end) throw new Error("malformed JSONB array")
+      return [out, end]
+    }
+    case 12: {
+      const out: Record<string, unknown> = {}
+      let p = start
+      while (p < end) {
+        const [k, afterKey] = jsonbElement(b, p, depth + 1)
+        if (typeof k !== "string") throw new Error("JSONB object key is not text")
+        const [v, next] = jsonbElement(b, afterKey, depth + 1)
+        out[k] = v
+        p = next
+      }
+      if (p !== end) throw new Error("malformed JSONB object")
+      return [out, end]
+    }
+    default:
+      throw new Error(`reserved JSONB element type ${type}`)
+  }
+}
+
+function jsonbHeader(type: number, size: number): number[] {
+  if (size <= 11) return [(size << 4) | type]
+  if (size <= 0xff) return [0xc0 | type, size]
+  if (size <= 0xffff) return [0xd0 | type, size >> 8, size & 0xff]
+  return [0xe0 | type, (size >>> 24) & 0xff, (size >>> 16) & 0xff, (size >>> 8) & 0xff, size & 0xff]
+}
+
+function jsonbParts(v: unknown, out: number[][], depth: number): void {
+  if (depth > 96) throw new Error("metadata nests too deeply for JSONB")
+  const leaf = (type: number, payload: Uint8Array): void => void out.push([...jsonbHeader(type, payload.length), ...payload])
+  if (v === null || v === undefined) return void out.push(jsonbHeader(0, 0))
+  if (v === true) return void out.push(jsonbHeader(1, 0))
+  if (v === false) return void out.push(jsonbHeader(2, 0))
+  if (typeof v === "number") {
+    if (!Number.isFinite(v)) return void out.push(jsonbHeader(0, 0))
+    return leaf(Number.isSafeInteger(v) ? 3 : 5, bytes(Number.isSafeInteger(v) ? String(v) : JSON.stringify(v)))
+  }
+  if (typeof v === "string") {
+    const escaped = JSON.stringify(v).slice(1, -1)
+    return leaf(escaped === v ? 7 : 8, bytes(escaped))
+  }
+  const children: number[][] = []
+  if (Array.isArray(v)) for (const item of v) jsonbParts(item, children, depth + 1)
+  else if (typeof v === "object")
+    for (const [k, item] of Object.entries(v as Record<string, unknown>)) {
+      if (item === undefined) continue
+      jsonbParts(k, children, depth + 1)
+      jsonbParts(item, children, depth + 1)
+    }
+  else throw new Error(`cannot store a ${typeof v} in JSONB`)
+  const size = children.reduce((n, c) => n + c.length, 0)
+  out.push(jsonbHeader(Array.isArray(v) ? 11 : 12, size))
+  out.push(...children)
+}
+
+/** A value as SQLite JSONB, the way MastraCode stores a thread's metadata. */
+export function encodeJsonb(v: unknown): Uint8Array {
+  const out: number[][] = []
+  jsonbParts(v, out, 0)
+  return Uint8Array.from(out.flat())
+}
+
+/** A thread's metadata, whether it is JSONB (as MastraCode writes it), JSON text, or missing. */
+export function metadataOf(v: unknown): Record<string, any> {
+  try {
+    const parsed = v instanceof Uint8Array ? decodeJsonb(v) : typeof v === "string" && v ? JSON.parse(v) : undefined
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? (parsed as Record<string, any>) : {}
+  } catch {
+    return {}
+  }
+}
+
+// --- Project identity ----------------------------------------------------------------------------------
+
+/** The folder with symbolic links resolved, as the process working directory MastraCode sees. */
+export function realDir(dir: string): string {
+  try {
+    return realpathSync(resolve(dir))
+  } catch {
+    return resolve(dir)
+  }
+}
+
+const normalizeGitUrl = (url: string) =>
+  url
+    .replace(/\.git$/, "")
+    .replace(/^git@([^:]+):/, "https://$1/")
+    .replace(/^ssh:\/\/git@/, "https://")
+    .toLowerCase()
+
+/**
+ * The resource id MastraCode scopes a project's threads by (utils/project.ts, as session-migrate reproduces
+ * it): a slug of the repository's name and the first 12 hex digits of the SHA-256 of its normalised remote
+ * URL; without a remote, of the main repository's folder (a worktree) or the project folder itself. Read
+ * from .git without running git.
+ */
+export function resourceIdFor(cwd: string): string {
+  let root = realDir(cwd)
+  let gitDir: string | undefined
+  for (let dir = root; ; dir = dirname(dir)) {
+    const git = join(dir, ".git")
+    if (exists(git)) {
+      try {
+        gitDir = isDir(git) ? git : resolve(dir, readFileSync(git, "utf8").replace(/^gitdir:\s*/, "").trim())
+        root = dir
+      } catch {}
+      break
+    }
+    if (dirname(dir) === dir) break
+  }
+  let url: string | undefined
+  let mainRepo: string | undefined
+  if (gitDir) {
+    let common = gitDir
+    try {
+      common = resolve(gitDir, readFileSync(join(gitDir, "commondir"), "utf8").trim())
+    } catch {}
+    if (common !== gitDir) mainRepo = dirname(common)
+    let config = ""
+    try {
+      config = readFileSync(join(common, "config"), "utf8")
+    } catch {}
+    url = config.match(/\[remote "origin"\][^[]*?url\s*=\s*(\S+)/)?.[1] ?? config.match(/\[remote "[^"]*"\][^[]*?url\s*=\s*(\S+)/)?.[1]
+  }
+  const source = url ? normalizeGitUrl(url) : (mainRepo ?? root)
+  const base = url ? url.replace(/\/+$/, "").split("/").pop()!.replace(/\.git$/, "") || "project" : basename(root)
+  const slug = base.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "")
+  return `${slug || "project"}-${createHash("sha256").update(source).digest("hex").slice(0, 12)}`
+}
+
+// --- The CLI -------------------------------------------------------------------------------------------
+
+/** The mastracode binary on PATH (read now, so a PATH set after start counts). */
+export const mastraBin = (): string | undefined => Bun.which("mastracode", { PATH: process.env.PATH ?? "" }) ?? undefined
+
+/** The installed MastraCode version, from `mastracode --version`. */
+export const mastraVersion = (bin = mastraBin()) => (bin ? versionOf(bin)?.match(/\d+\.\d+\.\d+/)?.[0] : undefined)
+
+/** Why MastraCode would read another store than `store`, from the environment and its settings; undefined when it reads this one. */
+export function otherStore(store: string): string | undefined {
+  const env = process.env
+  if (env.MASTRA_STORAGE_BACKEND && env.MASTRA_STORAGE_BACKEND !== "libsql") return `MASTRA_STORAGE_BACKEND=${env.MASTRA_STORAGE_BACKEND} points MastraCode at a remote store`
+  if (env.MASTRA_DB_URL && resolve(env.MASTRA_DB_URL.replace(/^file:(\/\/)?/, "")) !== store) return "MASTRA_DB_URL points MastraCode at another store"
+  if (env.MASTRA_DB_PATH && resolve(env.MASTRA_DB_PATH) !== store) return `MASTRA_DB_PATH points MastraCode at ${env.MASTRA_DB_PATH}`
+  if (env.MASTRA_APP_DATA_DIR && join(resolve(env.MASTRA_APP_DATA_DIR), "mastra.db") !== store) return `MASTRA_APP_DATA_DIR points MastraCode at ${env.MASTRA_APP_DATA_DIR}`
+  const storage = readJson<{ storage?: { backend?: unknown; libsql?: { url?: unknown } } }>(join(dirname(store), "settings.json"))?.storage
+  if (typeof storage?.backend === "string" && storage.backend !== "libsql") return `MastraCode's settings use the ${storage.backend} storage backend`
+  if (typeof storage?.libsql?.url === "string" && !storage.libsql.url.startsWith("file:")) return "MastraCode's settings use a remote LibSQL store"
+  return undefined
+}
+
+/** Why the store cannot be written now: a process holding it open, or MastraCode running; undefined when it is free. */
+export function storeInUse(store: string): string | undefined {
+  const files = [store, `${store}-wal`].filter(exists)
+  if (files.length) {
+    try {
+      const p = Bun.spawnSync(["lsof", "-t", "--", ...files], { stdout: "pipe", stderr: "pipe", timeout: 10_000 })
+      const pids = p.stdout.toString().split(/\s+/).filter((pid) => pid && Number(pid) !== process.pid)
+      if (pids.length) return `the MastraCode store is open in another process (pid ${pids.join(", ")}); close MastraCode first`
+    } catch {
+      // No lsof: the process checks below still apply.
+    }
+  }
+  if (isRunning("mastracode")) return "MastraCode is running; close it first, since it holds the session store open"
+  try {
+    const p = Bun.spawnSync(["pgrep", "-f", "mastracode/dist/cli|(^|/)mastracode( |$)"], { stdout: "pipe", stderr: "pipe" })
+    const pids = p.stdout.toString().split(/\s+/).filter((pid) => pid && Number(pid) !== process.pid)
+    if (pids.length) return "MastraCode is running; close it first, since it holds the session store open"
+  } catch {}
+  return undefined
+}