@100xprompt/brain 0.0.0-stage → 0.1.1

package/src/session/attachments.ts

@@ -0,0 +1,53 @@
+// Pasted images travel as files under ~/.brain/attachments/<hash>.<ext>, referenced by `Attachment.path`, so the
+// portable session stays small and every writer that can embed an image reads the same file.
+import { createHash } from "node:crypto"
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs"
+import { homedir } from "node:os"
+import { extname, join } from "node:path"
+import { homeDir } from "../fsutil.ts"
+import type { Attachment } from "./types.ts"
+
+export const IMAGE_TYPES: Record<string, string> = { ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".gif": "image/gif", ".webp": "image/webp" }
+const EXT = Object.fromEntries(Object.entries(IMAGE_TYPES).filter(([e]) => e !== ".jpeg").map(([e, m]) => [m, e]))
+/** Larger images stay behind and are counted as lost, as models reject them anyway. */
+export const IMAGE_LIMIT = 5 * 1024 * 1024
+
+/** <home>/.brain/attachments, with the same home as everything else the brain stores (BRAIN_HOME, else HOME). */
+export const attachmentDir = () => join(homeDir() || homedir(), ".brain", "attachments")
+
+/** Saves base64 image bytes and returns the attachment, or undefined when they are not a usable image. */
+export function keepImage(base64: string, mime: string | undefined): Attachment | undefined {
+  const ext = mime ? EXT[mime] : undefined
+  if (!ext || base64.length > IMAGE_LIMIT * 1.4) return undefined
+  try {
+    const bytes = Buffer.from(base64, "base64")
+    if (!bytes.length || bytes.length > IMAGE_LIMIT) return undefined
+    const path = join(attachmentDir(), `${createHash("sha256").update(bytes).digest("hex").slice(0, 24)}${ext}`)
+    if (!existsSync(path)) {
+      mkdirSync(attachmentDir(), { recursive: true })
+      writeFileSync(path, bytes)
+    }
+    return { kind: "image", path, mime: mime! }
+  } catch {
+    return undefined
+  }
+}
+
+/** The `data:` URL of a kept image, when its file is still there and small enough. */
+export function imageDataUrl(a: Attachment): string | undefined {
+  if (a.kind !== "image" || !a.path) return undefined
+  const mime = a.mime ?? IMAGE_TYPES[extname(a.path).toLowerCase()]
+  if (!mime || !Object.values(IMAGE_TYPES).includes(mime)) return undefined
+  try {
+    if (statSync(a.path).size > IMAGE_LIMIT) return undefined
+    return `data:${mime};base64,${readFileSync(a.path).toString("base64")}`
+  } catch {
+    return undefined
+  }
+}
+
+/** Splits a `data:image/...;base64,...` URL into its parts. */
+export function parseDataUrl(url: unknown): { mime: string; base64: string } | undefined {
+  const m = typeof url === "string" ? /^data:(image\/[a-z+.-]+);base64,(.+)$/s.exec(url) : null
+  return m ? { mime: m[1]!, base64: m[2]! } : undefined
+}

package/src/session/peekcache.ts

@@ -0,0 +1,50 @@
+// A cache for the cheap summary a reader makes of each session when listing (title, folder, last activity). An entry is
+// valid while the file's size and modified time (and `salt`, for a sibling file the summary also reads) are unchanged,
+// so a session that gets a new message is read again and nothing goes stale. Lives under <home>/.brain/cache/.
+// BRAIN_NO_CACHE=1 turns it off. `version` must change whenever the summary's logic changes.
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import { dirname, join } from "node:path"
+
+interface Entry {
+  m: number
+  s: number
+  k: number
+  v: unknown
+}
+
+export function peekCache(home: string, name: string, version: number) {
+  const off = process.env.BRAIN_NO_CACHE === "1"
+  const file = join(home, ".brain", "cache", `${name}-v${version}.json`)
+  let map: Record<string, Entry> = {}
+  if (!off) {
+    try {
+      map = JSON.parse(readFileSync(file, "utf8"))
+    } catch {}
+  }
+  const used = new Set<string>()
+  let dirty = false
+  return {
+    async get<T>(path: string, st: { mtimeMs: number; size: number }, salt: number, compute: () => Promise<T>): Promise<T> {
+      used.add(path)
+      const hit = map[path]
+      if (!off && hit && hit.m === st.mtimeMs && hit.s === st.size && hit.k === salt) return hit.v as T
+      const v = await compute()
+      if (!off) {
+        map[path] = { m: st.mtimeMs, s: st.size, k: salt, v }
+        dirty = true
+      }
+      return v
+    },
+    /** Writes the cache back, dropping entries for files that were not asked for (deleted sessions). */
+    flush() {
+      if (off) return
+      const stale = Object.keys(map).filter((p) => !used.has(p))
+      if (!dirty && !stale.length) return
+      for (const p of stale) delete map[p]
+      try {
+        mkdirSync(dirname(file), { recursive: true })
+        writeFileSync(file, JSON.stringify(map))
+      } catch {}
+    },
+  }
+}

package/src/session/types.ts

@@ -0,0 +1,104 @@
+// The portable session, brain-session/v1: what every reader produces and every writer consumes.
+// Design: docs/sessions/2026-11-08-session-switcher.md, section 3.1. Shaped on OpenTelemetry's GenAI
+// message conventions, with ideas from Harbor's ATIF.
+//
+// A session is a header and a flat, ordered list of turns. Flat on purpose: tools group the same events
+// differently (Claude Code puts text and tool calls in one assistant message, Cursor puts a call and its
+// result in one bubble, Codex gives each its own record), so writers regroup consecutive turns into
+// whatever their tool expects. Serialised as JSONL: the header line, then one line per turn.
+
+export const FORMAT = "brain-session/v1"
+
+/** What a tool call does, whatever the tool calls it, so a writer can map it onto its own tool names. */
+export type ToolKind = "read" | "edit" | "write" | "shell" | "search" | "list" | "web" | "mcp" | "task" | "todo" | "ask" | "other"
+
+export interface Usage {
+  input?: number
+  output?: number
+  cacheRead?: number
+  cacheWrite?: number
+}
+
+export interface Attachment {
+  kind: "image" | "file"
+  /** Where the bytes are, when they were kept: a path on this machine. */
+  path?: string
+  mime?: string
+  name?: string
+}
+
+export interface Project {
+  /** The folder the session ran in. */
+  cwd?: string
+  gitRemote?: string
+  gitBranch?: string
+  gitCommit?: string
+}
+
+export interface SessionHeader {
+  format: typeof FORMAT
+  /** Portable id: `<tool>:<sourceId>`. */
+  id: string
+  /** Reader id of the tool the session came from, e.g. "claude-code". */
+  tool: string
+  /** The tool version that wrote the session, from the session itself where it says. */
+  toolVersion?: string
+  /** The session's id in its own tool. */
+  sourceId: string
+  /** The file or database the session was read from. */
+  sourcePath?: string
+  title?: string
+  project: Project
+  startedAt?: string
+  updatedAt?: string
+  /** Models that answered, in order of first use. */
+  models: string[]
+  /** Where this session came from, when it is a fork, a subagent, or a continuation of another. */
+  parent?: { id: string; kind: "fork" | "subagent" | "continued" }
+  /**
+   * What did not survive reading, as short phrases ("signed reasoning (12 blocks)", "images (2)",
+   * "unknown record types: frame-link"). Writers append what they drop in turn.
+   */
+  lost: string[]
+}
+
+export type Turn =
+  | { kind: "user"; at?: string; text: string; attachments?: Attachment[] }
+  | { kind: "assistant"; at?: string; text: string; model?: string; usage?: Usage }
+  | {
+      kind: "tool_call"
+      at?: string
+      /** Unique within the session; writers remap it to their tool's id style. */
+      id: string
+      /** The tool's own name for it, e.g. "Bash", "run_terminal_cmd", "shell". */
+      name: string
+      toolKind: ToolKind
+      input: unknown
+    }
+  | {
+      kind: "tool_result"
+      at?: string
+      /** The id of the tool_call this answers. */
+      callId: string
+      ok: boolean
+      output: string
+      /** The output was cut; `fullPath` holds all of it when it was kept. */
+      truncated?: boolean
+      fullPath?: string
+    }
+  | { kind: "file_edit"; at?: string; path: string; patch?: string; callId?: string }
+  /** Readable reasoning only. Signed or encrypted reasoning never crosses tools: it is counted in `lost`. */
+  | { kind: "reasoning"; at?: string; text: string }
+  /** A summary that replaced the turns before it (the tool's own compaction). */
+  | { kind: "compaction"; at?: string; summary: string }
+  /** A subagent ran here; its session is in `Session.children` under this id. */
+  | { kind: "subagent"; at?: string; sessionId: string; callId?: string; description?: string }
+
+export type TurnKind = Turn["kind"]
+
+export interface Session {
+  header: SessionHeader
+  turns: Turn[]
+  /** Subagent sessions, referenced by `subagent` turns. */
+  children?: Session[]
+}

package/src/session/util.ts

@@ -0,0 +1,130 @@
+import { FORMAT, type Session, type SessionHeader, type ToolKind, type Turn, type TurnKind } from "./types.ts"
+
+/** Tool outputs longer than this are cut when converted; the reader keeps a path to the full text where it can. */
+export const OUTPUT_LIMIT = 20_000
+
+const KIND_BY_NAME: Array<[RegExp, ToolKind]> = [
+  [/^mcp[_-]|^mcp__|CallDynamicTool|GetDynamicTools|use_mcp_tool|access_mcp_resource/i, "mcp"],
+  [/^(Agent|Task|spawn_agent|delegate|subagent|new_task)/i, "task"],
+  [/todo|update_plan/i, "todo"],
+  [/ask_?(user_?)?question|AskUserQuestion|AskQuestion|ask_followup|request_user_input/i, "ask"],
+  [/web_?(search|fetch)|WebFetch|WebSearch|fetch_url|fetch_webpage|browser/i, "web"],
+  [/(str_?replace|search_replace|apply_patch|apply_diff|replace_in_file|replace_string_in_file|^replace$|insert_content|edit_file|multi_?edit|^Edit$|^MultiEdit$|StrReplace|insert_edit)/i, "edit"],
+  [/(^Write$|write_file|write_to_file|create_file|^create$|new_file)/i, "write"],
+  [/(^Read$|read_file|view_file|view_image|open_file|^view$|cat_file|read_many_files)/i, "read"],
+  [/(grep|ripgrep|search|find|^Glob$|glob|codebase_search|semantic|list_code_definition)/i, "search"],
+  [/(list_dir|list_files|^LS$|ls_dir|list_directory)/i, "list"],
+  [/(bash|shell|terminal|command|exec|run_cmd|local_shell|powershell|write_stdin)/i, "shell"],
+]
+
+/** What a tool call does, from its name: "run_terminal_cmd" and "Bash" are both "shell". */
+export function toolKindOf(name: string): ToolKind {
+  for (const [re, kind] of KIND_BY_NAME) if (re.test(name)) return kind
+  return "other"
+}
+
+/** Text cut to `limit` characters, keeping the start and the end, and whether it was cut. */
+export function clip(text: string, limit = OUTPUT_LIMIT): { text: string; truncated: boolean } {
+  if (text.length <= limit) return { text, truncated: false }
+  const half = Math.floor((limit - 40) / 2)
+  return { text: `${text.slice(0, half)}\n[... ${text.length - 2 * half} characters cut ...]\n${text.slice(-half)}`, truncated: true }
+}
+
+/** Any value as text: strings as they are, everything else as JSON. */
+export function asText(v: unknown): string {
+  if (v === undefined || v === null) return ""
+  if (typeof v === "string") return v
+  try {
+    return JSON.stringify(v)
+  } catch {
+    return String(v)
+  }
+}
+
+/** A timestamp in ISO form, from ISO strings or epoch seconds/milliseconds; undefined when it is neither. */
+export function iso(v: unknown): string | undefined {
+  if (typeof v === "string" && v) {
+    const t = Date.parse(v)
+    return Number.isFinite(t) ? new Date(t).toISOString() : undefined
+  }
+  if (typeof v === "number" && Number.isFinite(v) && v > 0) return new Date(v < 1e12 ? v * 1000 : v).toISOString()
+  return undefined
+}
+
+export function header(tool: string, sourceId: string, fields: Partial<Omit<SessionHeader, "format" | "id" | "tool" | "sourceId">> = {}): SessionHeader {
+  return { format: FORMAT, id: `${tool}:${sourceId}`, tool, sourceId, project: {}, models: [], lost: [], ...fields }
+}
+
+/** Adds a model to the header's list once. */
+export function noteModel(h: SessionHeader, model: string | undefined) {
+  if (model && !h.models.includes(model)) h.models.push(model)
+}
+
+/** Counts things that were dropped while reading, e.g. lost.add("signed reasoning"), then lost.flush(header). */
+export function lossCounter() {
+  const counts = new Map<string, number>()
+  return {
+    add(what: string, n = 1) {
+      counts.set(what, (counts.get(what) ?? 0) + n)
+    },
+    flush(h: SessionHeader) {
+      for (const [what, n] of counts) h.lost.push(`${what} (${n})`)
+      counts.clear()
+    },
+  }
+}
+
+export function countTurns(s: Session): Record<TurnKind, number> {
+  const out = { user: 0, assistant: 0, tool_call: 0, tool_result: 0, file_edit: 0, reasoning: 0, compaction: 0, subagent: 0 } as Record<TurnKind, number>
+  for (const t of s.turns) out[t.kind]++
+  return out
+}
+
+/** Tool calls without a result and results without a call: a reader or writer that loses pairing shows up here. */
+export function unpaired(s: Session): { calls: string[]; results: string[] } {
+  const calls = new Set(s.turns.filter((t) => t.kind === "tool_call").map((t) => (t as Extract<Turn, { kind: "tool_call" }>).id))
+  const results = new Set(s.turns.filter((t) => t.kind === "tool_result").map((t) => (t as Extract<Turn, { kind: "tool_result" }>).callId))
+  return { calls: [...calls].filter((c) => !results.has(c)), results: [...results].filter((r) => !calls.has(r)) }
+}
+
+export function toJsonl(s: Session): string {
+  const lines = [JSON.stringify(s.header), ...s.turns.map((t) => JSON.stringify(t))]
+  for (const c of s.children ?? []) lines.push(JSON.stringify({ kind: "child", session: c }))
+  return `${lines.join("\n")}\n`
+}
+
+export function fromJsonl(text: string): Session {
+  const lines = text.split("\n").filter((l) => l.trim())
+  const header = JSON.parse(lines[0]!) as SessionHeader
+  if (header.format !== FORMAT) throw new Error(`not a ${FORMAT} file (format: ${String(header.format)})`)
+  const turns: Turn[] = []
+  const children: Session[] = []
+  for (const l of lines.slice(1)) {
+    const v = JSON.parse(l) as Turn | { kind: "child"; session: Session }
+    if (v.kind === "child") children.push((v as { session: Session }).session)
+    else turns.push(v as Turn)
+  }
+  return children.length ? { header, turns, children } : { header, turns }
+}
+
+/** The first user message, the usual best guess at a session's purpose and title. */
+export function firstUserText(s: Session): string | undefined {
+  return (s.turns.find((t) => t.kind === "user" && t.text.trim() && !isInjected(t.text)) as Extract<Turn, { kind: "user" }> | undefined)?.text
+}
+
+/**
+ * Text a tool injected into the conversation (reminders, background-task notices, slash-command echoes)
+ * rather than something the person typed. Writers keep it for the model but must not present it as the
+ * person's own message in a history list or title.
+ */
+const INJECTED_TAG = "system-reminder|task-notification|ci-monitor-event|command-name|command-message|command-args|local-command-stdout|local-command-stderr|local-command-caveat"
+const LEADING_BLOCK = new RegExp(`^<(${INJECTED_TAG})\\b[^>]*>[\\s\\S]*?(?:</\\1>|$)\\s*`)
+
+/** The text with any leading injected blocks removed (what the person actually wrote, if anything). */
+export function withoutInjected(text: string): string {
+  let t = text.trimStart()
+  for (let m = LEADING_BLOCK.exec(t); m; m = LEADING_BLOCK.exec(t)) t = t.slice(m[0].length)
+  return t
+}
+/** True when the text is nothing but injected blocks. */
+export const isInjected = (text: string): boolean => !withoutInjected(text).trim()

package/src/sqlite.ts

@@ -0,0 +1,48 @@
+import { Database } from "bun:sqlite"
+import { copyFileSync, existsSync, mkdtempSync, rmSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { basename, join } from "node:path"
+
+// Reading another tool's SQLite store without touching it. Opening a live database, even read-only,
+// can write its -shm file, and `immutable=1` skips whatever is still in the write-ahead log, which is
+// where the newest turns are (Cursor, Codex, Warp, Zed and OpenCode 2 all use WAL). So the database is
+// copied together with its -wal and -shm files and the copy is read.
+
+export interface Snapshot {
+  db: Database
+  close(): void
+}
+
+export function snapshot(path: string): Snapshot {
+  const dir = mkdtempSync(join(tmpdir(), "brain-sqlite-"))
+  let db: Database
+  try {
+    const copy = join(dir, basename(path))
+    copyFileSync(path, copy)
+    for (const side of ["-wal", "-shm"]) if (existsSync(path + side)) copyFileSync(path + side, copy + side)
+    // Opened read-write: it is our copy, and SQLite needs to write the -shm file to read the log.
+    // (Bun rejects an explicit { readonly: false }; the default is read-write.)
+    db = new Database(copy)
+  } catch (e) {
+    // The copy holds the person's data: never leave it behind.
+    rmSync(dir, { recursive: true, force: true })
+    throw e
+  }
+  return {
+    db,
+    close() {
+      db.close()
+      rmSync(dir, { recursive: true, force: true })
+    },
+  }
+}
+
+/** Runs `use` on a snapshot of the database and always cleans up. */
+export function withSnapshot<T>(path: string, use: (db: Database) => T): T {
+  const s = snapshot(path)
+  try {
+    return use(s.db)
+  } finally {
+    s.close()
+  }
+}