@100xprompt/brain 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,405 @@
+import type { Database } from "bun:sqlite"
+import { createHash } from "node:crypto"
+import { dirname, join, resolve } from "node:path"
+import type { Session, SessionHeader, Turn } from "../../session/types.ts"
+import { appSupport, exists, gitInfo, ls, mtime, readJson } from "../../fsutil.ts"
+import { withSnapshot } from "../../sqlite.ts"
+import { clip, header, iso, lossCounter, noteModel, toolKindOf } from "../../session/util.ts"
+import type { Reader, SessionRef, Writer } from "../types.ts"
+import { bytes, messageOrder, toolFailed, toolResultText } from "../cursor-ide/agentkv.ts"
+import { type Loss, userText } from "../cursor-ide/transcripts.ts"
+import { Workspaces } from "../cursor-ide/workspaces.ts"
+
+// Cursor CLI chats (catalogue entry 24 and its fact-check). Each chat is its own SQLite store,
+// <home>/.cursor/chats/<md5 of the resolved cwd>/<agentId>/store.db, and ACP sessions keep the same store
+// at <home>/.cursor/acp-sessions/<sessionId>/store.db. A store has two tables (cursor-agent 2025.09 and
+// 2026.10 bundles agree): meta(key, value), whose key "0" holds the chat's metadata as JSON, hex-encoded
+// by both bundles (plain JSON is accepted too); and blobs(id, data), content-addressed by SHA-256. JSON
+// blobs are AI-SDK messages (role user/assistant/tool/system; parts text, reasoning, tool-call,
+// tool-result); the rest are protobuf conversation state. Message order comes from the protobuf root
+// that meta's latestRootBlobId names (agentkv.ts), not from the order blobs were stored in, which
+// differs (blobs are written with INSERT OR REPLACE); only when the root cannot be read is the stored
+// order used. 2026.x adds a meta.json sidecar per chat that `agent ls`
+// reads ({schemaVersion 1, title, createdAtMs, updatedAtMs, hasConversation, isSubagent, cwd}); an ACP
+// session's meta.json is {schemaVersion 1, cwd, title}. Subagents are chats of their own in the same
+// folder, with subagentInfo {parentAgentId, toolCallId} in their metadata. No CLI chat exists on the Mac
+// this was written on, so the shapes come from the two bundles and the IDE's agentKv blobs, which the
+// same harness writes. There is no writer: in phase 1 Cursor is reached by the continuation brief.
+
+const TOOL = "cursor-cli"
+
+/** Where cursor-agent keeps its state (CURSOR_CONFIG_DIR and XDG_CONFIG_HOME overrides are not followed). */
+const cursorDir = (home: string) => join(home, ".cursor")
+const chatsDir = (home: string) => join(cursorDir(home), "chats")
+const acpDir = (home: string) => join(cursorDir(home), "acp-sessions")
+
+/** The chats folder for a project: md5 of the resolved path, as cursor-agent names it. */
+export const bucketOf = (cwd: string) => createHash("md5").update(resolve(cwd)).digest("hex")
+
+/** The default chat name, which says nothing. */
+const DEFAULT_NAME = "New Agent"
+
+const str = (v: unknown) => (typeof v === "string" && v ? v : undefined)
+
+/** Milliseconds from a time cursor-agent stored in seconds, milliseconds, micro- or nanoseconds. */
+function ms(v: unknown): number | undefined {
+  const t = typeof v === "number" ? v : typeof v === "string" && /^\d+$/.test(v) ? Number(v) : Number.NaN
+  if (!Number.isFinite(t) || t <= 0) return undefined
+  return t < 1e11 ? t * 1000 : t >= 1e17 ? t / 1e6 : t >= 1e14 ? t / 1e3 : t
+}
+
+/** When the store was last written: its write-ahead log is newer than the file while uncheckpointed. */
+const storeTime = (store: string) => [mtime(store), mtime(`${store}-wal`)].filter((x): x is string => !!x).sort().pop()
+
+const hasTable = (db: Database, name: string) => !!db.query("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?").get(name)
+
+const asString = (v: unknown) => (typeof v === "string" ? v : v instanceof Uint8Array ? new TextDecoder().decode(v) : undefined)
+
+/** The metadata JSON from meta key "0": hex of the JSON text in both bundles, plain JSON in some builds. */
+export function decodeMeta(value: unknown): Record<string, any> | undefined {
+  const t = asString(value)?.trim()
+  if (!t) return undefined
+  const text = /^[0-9a-f]+$/i.test(t) && t.length % 2 === 0 ? Buffer.from(t, "hex").toString("utf8") : t
+  try {
+    const v = JSON.parse(text)
+    return v && typeof v === "object" && !Array.isArray(v) ? v : undefined
+  } catch {
+    return undefined
+  }
+}
+
+interface Store {
+  meta: Record<string, any>
+  /** PRAGMA user_version: the store schema (1 in both bundles). */
+  version?: number
+}
+
+function readMeta(db: Database): Store {
+  const version = (db.query("PRAGMA user_version").get() as { user_version?: number } | null)?.user_version
+  if (!hasTable(db, "meta")) return { meta: {}, version }
+  const rows = db.query("SELECT key, value FROM meta").all() as Array<{ key: string; value: unknown }>
+  const zero = rows.find((r) => r.key === "0")
+  const meta = zero ? decodeMeta(zero.value) : undefined
+  // Without key "0", the fields as rows of their own (agentId, name, createdAt, lastUsedModel...).
+  return { meta: meta ?? Object.fromEntries(rows.filter((r) => r.key !== "0").map((r) => [r.key, asString(r.value)])), version }
+}
+
+// ---- list -------------------------------------------------------------------------------------------
+
+interface Found {
+  id: string
+  store: string
+  kind: "chat" | "acp"
+  title?: string
+  cwd?: string
+  updatedAt?: string
+}
+
+/** What `agent ls` shows for one chat folder, from its meta.json, else from the store's metadata row. */
+function chatEntry(id: string, dir: string): Found | undefined {
+  const store = join(dir, "store.db")
+  const side = readJson<Record<string, any>>(join(dir, "meta.json"))
+  if (side && typeof side.createdAtMs === "number") {
+    if (side.isSubagent === true || side.hasConversation !== true) return undefined
+    return { id, store, kind: "chat", title: str(side.title), cwd: str(side.cwd), updatedAt: iso(ms(side.updatedAtMs)) ?? storeTime(store) }
+  }
+  // Older builds keep no sidecar; cursor-agent then opens the store, and so does this.
+  let entry: Found | undefined
+  try {
+    entry = withSnapshot(store, (db) => {
+      const { meta } = readMeta(db)
+      if (meta.subagentInfo) return undefined // read with its parent
+      const blobs = hasTable(db, "blobs") ? ((db.query("SELECT count(*) AS n FROM blobs").get() as { n: number }).n ?? 0) : 0
+      if (!str(meta.latestRootBlobId) && !blobs) return undefined // never used
+      const name = str(meta.name)
+      return { id, store, kind: "chat" as const, title: name !== DEFAULT_NAME ? name : undefined, cwd: str(meta.workspacePath), updatedAt: storeTime(store) }
+    })
+  } catch {
+    return undefined // not a store cursor-agent could open either
+  }
+  return entry
+}
+
+async function list(home: string): Promise<SessionRef[]> {
+  const found: Found[] = []
+  for (const bucket of ls(chatsDir(home))) {
+    for (const id of ls(join(chatsDir(home), bucket))) {
+      const dir = join(chatsDir(home), bucket, id)
+      if (!exists(join(dir, "store.db"))) continue
+      const e = chatEntry(id, dir)
+      if (e) found.push(e)
+    }
+  }
+  for (const id of ls(acpDir(home))) {
+    const store = join(acpDir(home), id, "store.db")
+    if (!exists(store)) continue
+    const side = readJson<Record<string, any>>(join(acpDir(home), id, "meta.json"))
+    found.push({ id, store, kind: "acp", title: str(side?.title), cwd: str(side?.cwd), updatedAt: storeTime(store) })
+  }
+  // A chat's folder is named by md5 of its cwd: match it against folders known from elsewhere.
+  if (found.some((f) => !f.cwd)) {
+    const byBucket = folderIndex(home, found.map((f) => f.cwd))
+    for (const f of found) if (!f.cwd && f.kind === "chat") f.cwd = byBucket.get(dirname(dirname(f.store)).split("/").pop()!)
+  }
+  return found
+    .map((f): SessionRef => ({
+      tool: TOOL,
+      sourceId: f.id,
+      path: f.store,
+      ...(f.title ? { title: f.title } : {}),
+      ...(f.cwd ? { cwd: f.cwd } : {}),
+      ...(f.updatedAt ? { updatedAt: f.updatedAt } : {}),
+      extra: { kind: f.kind },
+    }))
+    .sort((a, b) => (b.updatedAt ?? "").localeCompare(a.updatedAt ?? ""))
+}
+
+/** md5 bucket → folder, for every folder known: sessions that record theirs and Cursor's workspaces. */
+function folderIndex(home: string, known: Array<string | undefined>): Map<string, string> {
+  const out = new Map<string, string>()
+  const folders = [...known.filter((x): x is string => !!x), ...new Workspaces(join(appSupport(home), "Cursor", "User", "workspaceStorage")).folders()]
+  for (const f of folders) out.set(bucketOf(f), f)
+  return out
+}
+
+// ---- read -------------------------------------------------------------------------------------------
+
+/** The text of a message's text parts (or its string content). */
+const textOf = (m: Record<string, any>) =>
+  typeof m.content === "string" ? m.content : Array.isArray(m.content) ? m.content.filter((p: any) => p?.type === "text" && typeof p.text === "string").map((p: any) => p.text).join("\n\n") : ""
+
+interface Conv {
+  h: SessionHeader
+  lost: Loss
+  turns: Turn[]
+  /** Original tool-call id → the id used in the session (made unique if a store repeats one). */
+  calls: Map<string, string>
+  used: Set<string>
+  fallbackModel?: string
+}
+
+function userTurns(m: Record<string, any>, c: Conv) {
+  const parts: Array<Record<string, any>> = typeof m.content === "string" ? [{ type: "text", text: m.content }] : Array.isArray(m.content) ? m.content : []
+  const texts: string[] = []
+  let at: string | undefined
+  let context = false
+  for (const p of parts) {
+    if (p?.type === "text" && typeof p.text === "string") {
+      const u = userText(p.text)
+      at ??= u.at
+      if (u.text) texts.push(u.text)
+      else context ||= u.context
+    } else if (p?.type === "image") c.lost.add("images")
+    else if (p?.type === "file") c.lost.add("attached files")
+    else c.lost.add(`unknown record types: user part ${String(p?.type)}`)
+  }
+  if (texts.length) c.turns.push({ kind: "user", ...(at ? { at } : {}), text: texts.join("\n\n") })
+  else if (context) c.lost.add("injected context messages")
+}
+
+function assistantTurns(m: Record<string, any>, c: Conv) {
+  const parts: Array<Record<string, any>> = typeof m.content === "string" ? [{ type: "text", text: m.content }] : Array.isArray(m.content) ? m.content : []
+  const model = str(m.providerOptions?.cursor?.modelName) ?? parts.map((p) => str(p?.providerOptions?.cursor?.modelName)).find(Boolean) ?? c.fallbackModel
+  noteModel(c.h, model)
+  let text = ""
+  const flush = () => {
+    if (text.trim()) c.turns.push({ kind: "assistant", text, ...(model ? { model } : {}) })
+    text = ""
+  }
+  for (const p of parts) {
+    switch (p?.type) {
+      case "text":
+        text += typeof p.text === "string" ? p.text : ""
+        break
+      case "reasoning":
+        flush()
+        if (typeof p.text === "string" && p.text.trim()) c.turns.push({ kind: "reasoning", text: p.text })
+        else if (p.signature || p.providerOptions?.anthropic?.signature) c.lost.add("signed reasoning")
+        break
+      case "redacted-reasoning":
+        c.lost.add("redacted reasoning")
+        break
+      case "tool-call": {
+        flush()
+        const orig = str(p.toolCallId) ?? `call-${c.used.size + 1}`
+        let id = orig
+        for (let n = 2; c.used.has(id); n++) id = `${orig}#${n}`
+        c.used.add(id)
+        c.calls.set(orig, id)
+        const name = str(p.toolName) ?? "unknown"
+        c.turns.push({ kind: "tool_call", id, name, toolKind: toolKindOf(name), input: p.args ?? p.input ?? {} })
+        break
+      }
+      default:
+        c.lost.add(`unknown record types: assistant part ${String(p?.type)}`)
+    }
+  }
+  flush()
+}
+
+function toolTurns(m: Record<string, any>, c: Conv) {
+  for (const p of (Array.isArray(m.content) ? m.content : []) as Array<Record<string, any>>) {
+    if (p?.type !== "tool-result") {
+      c.lost.add(`unknown record types: tool part ${String(p?.type)}`)
+      continue
+    }
+    const images = Array.isArray(p.experimental_content) ? p.experimental_content.filter((x: any) => x?.type === "image").length : 0
+    if (images) c.lost.add("images", images)
+    const orig = str(p.toolCallId) ?? ""
+    const out = clip(toolResultText(p))
+    c.turns.push({ kind: "tool_result", callId: c.calls.get(orig) ?? orig, ok: !toolFailed(m, p), output: out.text, ...(out.truncated ? { truncated: true } : {}) })
+  }
+}
+
+/**
+ * The JSON messages of a store in conversation order: as the protobuf root lists them, else, when the
+ * root cannot be read, in the order they were stored. Protobuf blobs are skipped.
+ */
+function messages(db: Database, meta: Record<string, any>, lost: Loss): Array<Record<string, any>> {
+  if (!hasTable(db, "blobs")) return []
+  let rows: Array<{ id: unknown; data: unknown }>
+  try {
+    rows = db.query("SELECT id, data FROM blobs ORDER BY rowid").all() as Array<{ id: unknown; data: unknown }>
+  } catch {
+    rows = db.query("SELECT id, data FROM blobs").all() as Array<{ id: unknown; data: unknown }>
+  }
+  const json = new Map<string, Record<string, any>>()
+  const decoder = new TextDecoder("utf-8", { fatal: true })
+  for (const r of rows) {
+    let text: string | undefined
+    try {
+      text = typeof r.data === "string" ? r.data : r.data instanceof Uint8Array ? decoder.decode(r.data) : undefined
+    } catch {
+      continue // binary: protobuf graph state
+    }
+    if (!text || text[0] !== "{") continue
+    let v: unknown
+    try {
+      v = JSON.parse(text)
+    } catch {
+      continue
+    }
+    if (v && typeof v === "object" && typeof (v as Record<string, unknown>).role === "string") json.set(String(r.id), v as Record<string, any>)
+    else lost.add("unknown record types: JSON blob without a role")
+  }
+  const one = db.query("SELECT data FROM blobs WHERE id = ?")
+  const blob = (id: string) => bytes((one.get(id) as { data: unknown } | null)?.data)
+  const rootId = str(meta.latestRootBlobId)?.toLowerCase()
+  const root = rootId ? blob(rootId) : undefined
+  const order = root ? messageOrder(root, blob) : undefined
+  if (!order?.some((id) => json.has(id))) {
+    if (json.size && rootId) lost.add("conversation order (root not readable; stored order used)")
+    return [...json.values()]
+  }
+  const missing = order.filter((id) => !json.has(id)).length
+  if (missing) lost.add("messages the root lists but the store lacks", missing)
+  // Messages no root lists (left by a rewind or an earlier state of the chat): Cursor's own transcript
+  // writer shows none of them either.
+  const listed = new Set(order)
+  const outside = [...json].filter(([id, m]) => !listed.has(id) && m.role !== "system").length
+  if (outside) lost.add("messages outside the conversation (not in its root)", outside)
+  return order.filter((id) => json.has(id)).map((id) => json.get(id)!)
+}
+
+interface Opened {
+  store: Store
+  messages: Array<Record<string, any>>
+  lost: Loss
+}
+
+function open(storePath: string): Opened {
+  return withSnapshot(storePath, (db) => {
+    const lost = lossCounter()
+    const store = readMeta(db)
+    return { store, messages: messages(db, store.meta, lost), lost }
+  })
+}
+
+/** Subagent chats in `bucket` spawned by `agentId`, with the tool call that spawned each. */
+function subagentsOf(bucket: string, agentId: string, self: string): Array<{ id: string; store: string; callId?: string }> {
+  const out: Array<{ id: string; store: string; callId?: string }> = []
+  for (const id of ls(bucket)) {
+    const store = join(bucket, id, "store.db")
+    if (id === self || !exists(store)) continue
+    const side = readJson<Record<string, any>>(join(bucket, id, "meta.json"))
+    if (side && side.isSubagent !== true && typeof side.createdAtMs === "number") continue // a sidecar says it is a main chat
+    try {
+      const info = withSnapshot(store, (db) => readMeta(db).meta.subagentInfo) as Record<string, any> | undefined
+      if (str(info?.parentAgentId) === agentId) out.push({ id, store, callId: str(info?.toolCallId) })
+    } catch {
+      /* unreadable sibling: not ours to report */
+    }
+  }
+  return out
+}
+
+function readStore(ref: { sourceId: string; path: string; kind: string; cwd?: string; updatedAt?: string }, home: string, depth: number): Session {
+  const { store, messages: msgs, lost } = open(ref.path)
+  const dir = dirname(ref.path)
+  const side = readJson<Record<string, any>>(join(dir, "meta.json"))
+  const meta = store.meta
+  const name = str(meta.name)
+  const h = header(TOOL, ref.sourceId, {
+    toolVersion: [store.version !== undefined ? `store v${store.version}` : undefined, typeof side?.schemaVersion === "number" ? `meta.json v${side.schemaVersion}` : undefined].filter(Boolean).join(", ") || undefined,
+    sourcePath: ref.path,
+    title: str(side?.title) ?? (name !== DEFAULT_NAME ? name : undefined),
+    startedAt: iso(ms(meta.createdAt) ?? ms(side?.createdAtMs)),
+    updatedAt: ref.updatedAt ?? iso(ms(side?.updatedAtMs)) ?? storeTime(ref.path),
+  })
+  const parent = str(meta.subagentInfo?.parentAgentId)
+  if (parent) h.parent = { id: `${TOOL}:${parent}`, kind: "subagent" }
+  const c: Conv = { h, lost, turns: [], calls: new Map(), used: new Set(), fallbackModel: str(meta.lastUsedModel) }
+  for (const m of msgs) {
+    // A compaction's summary comes back as an ordinary message flagged isSummary; it is not something
+    // the person or the model said (Cursor's transcript writer leaves it out).
+    if (m.providerOptions?.cursor?.isSummary === true) {
+      const summary = textOf(m)
+      if (summary.trim()) c.turns.push({ kind: "compaction", summary })
+    } else if (m.role === "user") userTurns(m, c)
+    else if (m.role === "assistant") assistantTurns(m, c)
+    else if (m.role === "tool") toolTurns(m, c)
+    else if (m.role !== "system") lost.add(`unknown record types: role ${String(m.role)}`) // the system prompt is Cursor's own; targets write theirs
+  }
+  if (!h.models.length) noteModel(h, str(meta.lastUsedModel))
+  if (!msgs.length && str(meta.latestRootBlobId)) lost.add("conversation kept only as protobuf state (not decoded)")
+
+  const cwd = ref.cwd ?? str(side?.cwd) ?? str(meta.workspacePath) ?? (ref.kind === "chat" ? folderIndex(home, []).get(dirname(dir).split("/").pop()!) : undefined)
+  h.project = { ...(cwd ? { cwd } : {}), ...gitInfo(cwd) }
+
+  // Subagents live beside the chat (or, for an ACP session, in its project's chats folder) and are placed
+  // after the tool call that started them.
+  const children: Session[] = []
+  const bucket = ref.kind === "chat" ? dirname(dir) : cwd ? join(chatsDir(home), bucketOf(cwd)) : undefined
+  const agentId = str(meta.agentId) ?? ref.sourceId
+  if (bucket && depth < 3) {
+    for (const sub of subagentsOf(bucket, agentId, ref.sourceId)) {
+      let child: Session
+      try {
+        child = readStore({ sourceId: sub.id, path: sub.store, kind: "chat", cwd }, home, depth + 1)
+      } catch {
+        lost.add("unreadable subagent chats")
+        continue
+      }
+      children.push(child)
+      const turn: Turn = { kind: "subagent", sessionId: child.header.id, ...(sub.callId ? { callId: c.calls.get(sub.callId) ?? sub.callId } : {}), ...(child.header.title ? { description: child.header.title } : {}) }
+      const at = sub.callId ? c.turns.findIndex((t) => t.kind === "tool_call" && t.id === (c.calls.get(sub.callId!) ?? sub.callId)) : -1
+      if (at < 0) c.turns.push(turn)
+      else {
+        // After the call's result when there is one, so the call and result stay together.
+        const res = c.turns.findIndex((t, i) => i > at && t.kind === "tool_result" && t.callId === (c.turns[at] as Extract<Turn, { kind: "tool_call" }>).id)
+        c.turns.splice((res >= 0 ? res : at) + 1, 0, turn)
+      }
+    }
+  }
+  lost.flush(h)
+  return children.length ? { header: h, turns: c.turns, children } : { header: h, turns: c.turns }
+}
+
+async function read(ref: SessionRef, home: string): Promise<Session> {
+  if (!exists(ref.path)) throw new Error(`no Cursor CLI store at ${ref.path}`)
+  const kind = ref.extra?.kind === "acp" || ref.path.startsWith(acpDir(home)) ? "acp" : "chat"
+  return readStore({ sourceId: ref.sourceId, path: ref.path, kind, ...(ref.cwd ? { cwd: ref.cwd } : {}), ...(ref.updatedAt ? { updatedAt: ref.updatedAt } : {}) }, home, 0)
+}
+
+export const readers: Reader[] = [{ tool: TOOL, label: "Cursor CLI", list, read }]
+export const writers: Writer[] = []

package/src/adapters/cursor-ide/agentkv.ts

@@ -0,0 +1,95 @@
+import { asText } from "../../session/util.ts"
+
+// Cursor's agent harness, in the IDE and the CLI alike, keeps the conversation the model sees as
+// content-addressed blobs: AI-SDK messages as JSON, plus a protobuf root, ConversationStateStructure,
+// that lists them in order. The order matters: blobs are written with INSERT OR REPLACE, so the order
+// they were stored in is not the conversation's (on the Mac this was written on, a tool result was
+// stored before the call that asked for it in 2 of 4 conversations).
+//
+// Only the fields needed for the order are read, by field number, from the protobuf wire format
+// (cursor-agent 2025.09 and 2026.10 bundles agree): 1 root_prompt_messages_json, the blob ids of the
+// current prompt's messages; 13 summary_archives (2026.10) and 11 summary_archive (older), blob ids of
+// ConversationSummaryArchive messages, whose field 1, summarized_messages, lists the messages a
+// compaction replaced. Cursor's own transcript writer reads the same: every archive's messages, then the
+// root's. Blob ids are 32 raw bytes, written as lower-case hex wherever a store keys blobs by text.
+
+/** The length-delimited fields of one protobuf message, by field number; undefined when the bytes are not protobuf. */
+export function protoFields(buf: Uint8Array): Map<number, Uint8Array[]> | undefined {
+  const out = new Map<number, Uint8Array[]>()
+  let i = 0
+  const varint = (): number | undefined => {
+    let v = 0
+    for (let shift = 1, n = 0; n < 10; n++, shift *= 128) {
+      if (i >= buf.length) return undefined
+      const b = buf[i++]!
+      v += (b & 0x7f) * shift
+      if (!(b & 0x80)) return v
+    }
+    return undefined
+  }
+  while (i < buf.length) {
+    const tag = varint()
+    if (tag === undefined || tag < 8) return undefined
+    const wire = tag % 8
+    if (wire === 0) {
+      if (varint() === undefined) return undefined
+    } else if (wire === 1) i += 8
+    else if (wire === 5) i += 4
+    else if (wire === 2) {
+      const n = varint()
+      if (n === undefined || i + n > buf.length) return undefined
+      const no = Math.floor(tag / 8)
+      out.set(no, [...(out.get(no) ?? []), buf.subarray(i, i + n)])
+      i += n
+    } else return undefined // groups (3, 4) are not used by these messages
+    if (i > buf.length) return undefined
+  }
+  return out
+}
+
+const hex = (b: Uint8Array) => Buffer.from(b).toString("hex")
+const ids = (f: Uint8Array[] | undefined) => (f ?? []).filter((b) => b.length === 32).map(hex)
+
+/**
+ * The blob ids of a conversation's messages, oldest first: each compaction's archived messages, then the
+ * current prompt's. Undefined when `root` is not a ConversationStateStructure that lists any message.
+ */
+export function messageOrder(root: Uint8Array, getBlob: (id: string) => Uint8Array | undefined): string[] | undefined {
+  const top = protoFields(root)
+  const prompt = ids(top?.get(1))
+  if (!top || !prompt.length) return undefined
+  const archives = [...new Set([...ids(top.get(13)), ...ids(top.get(11))])]
+  const order: string[] = []
+  for (const a of archives) {
+    const blob = getBlob(a)
+    order.push(...ids(blob ? protoFields(blob)?.get(1) : undefined))
+  }
+  order.push(...prompt)
+  return [...new Set(order)] // a message kept across a compaction is listed in both; it happened once
+}
+
+/** The root of an IDE composer: composerData.conversationState is "~" and the root's bytes in base64. */
+export function composerRoot(state: unknown): Uint8Array | undefined {
+  if (typeof state !== "string" || !state.startsWith("~") || state.length < 2) return undefined
+  const b = Buffer.from(state.slice(1), "base64")
+  return b.length ? new Uint8Array(b) : undefined
+}
+
+/** A blob's bytes from a SQLite value, which is a BLOB; text values cannot hold protobuf intact. */
+export const bytes = (v: unknown) => (v instanceof Uint8Array ? v : undefined)
+
+/** What a tool-result part returned to the model: its result, else the text parts of experimental_content. */
+export function toolResultText(p: Record<string, any>): string {
+  if (typeof p.result === "string") return p.result
+  if (p.result !== undefined && p.result !== null) return asText(p.result)
+  if (Array.isArray(p.experimental_content)) return p.experimental_content.map((c: any) => (c?.type === "text" ? String(c.text ?? "") : `[${String(c?.type ?? "part")}]`)).join("\n")
+  return ""
+}
+
+/**
+ * Whether a tool message reports failure. The harness flags it on the message
+ * (providerOptions.cursor.highLevelToolCallResult.isError), not on the part; every tool message seen holds
+ * one result, so the message's flag is trusted only then.
+ */
+export const toolFailed = (m: Record<string, any>, p: Record<string, any>) =>
+  p.isError === true || (Array.isArray(m.content) && m.content.length === 1 && m.providerOptions?.cursor?.highLevelToolCallResult?.isError === true)