@100xprompt/brain 0.0.0-stage → 0.1.1

package/src/dashboard/cli.ts

@@ -0,0 +1,148 @@
+// `brain dashboard [push|on|off|status] [--quiet] [--no-open]`: this machine's report for the Brain view of the 100xprompt
+// console (https://100xprompt.com/dashboard?view=brain). The dashboard is on the website only; brain sends the report
+// (report.ts, send.ts) and opens the page.
+import type { Reader } from "../adapters/types.ts"
+import type { Env } from "../gateway/common.ts"
+import { openInBrowser } from "../gateway/signin.ts"
+import { readConversions } from "./conversions.ts"
+import { DASHBOARD_URL, gatewayUrl, noticeOnce, reportUrl, sendingOff, sendReport, signedIn, startScheduled } from "./send.ts"
+import type { BrainReport } from "./report.ts"
+import { readCache, readSettings, updateSettings } from "./state.ts"
+
+const USAGE = [
+  "brain dashboard [--no-open]     count this machine's sessions, send its report to your 100xprompt account now, and open the Brain view",
+  "brain dashboard push [--quiet]  send the report now, without counting sessions (the last counts are reused)",
+  "brain dashboard off | on        stop or start sending reports from this machine (kept in ~/.brain/dashboard.json)",
+  "brain dashboard status          whether reports are sent, and when the last one went out",
+]
+
+const FLAGS = new Set(["--quiet", "--no-open", "--at", "--help", "-h"])
+
+function ago(iso: string | undefined, now = Date.now()): string {
+  const t = iso ? Date.parse(iso) : NaN
+  if (!Number.isFinite(t)) return ""
+  const m = Math.max(0, Math.round((now - t) / 60_000))
+  return m < 1 ? "just now" : m < 60 ? `${m}m ago` : m < 48 * 60 ? `${Math.round(m / 60)}h ago` : `${Math.round(m / 1440)}d ago`
+}
+
+const plural = (n: number, one: string, many = `${one}s`) => `${n} ${n === 1 ? one : many}`
+
+/** One line on what a report holds. */
+export function summary(r: BrainReport): string {
+  const counted = r.harnesses.filter((h) => h.sessions !== null)
+  const sessions = counted.reduce((n, h) => n + (h.sessions ?? 0), 0)
+  const connected = r.harnesses.filter((h) => h.gateway === "connected").length
+  return `${plural(r.harnesses.length, "tool")} (${connected} connected to the gateway)${counted.length ? `, ${plural(sessions, "session")}` : ""}, ${plural(r.totals.conversions, "conversion")}`
+}
+
+export async function dashboardCommand(
+  args: string[],
+  home: string,
+  io: { out(l: string): void; err(l: string): void } = { out: (l) => process.stdout.write(`${l}\n`), err: (l) => process.stderr.write(`${l}\n`) },
+  deps: { env?: Env; fetchImpl?: typeof fetch; open?: (url: string) => void; countTimeoutMs?: number; readers?: Reader[] } = {},
+): Promise<number> {
+  const env = deps.env ?? process.env
+  const atAt = args.indexOf("--at")
+  const words = args.filter((a, i) => !a.startsWith("-") && !(atAt >= 0 && i === atAt + 1))
+  const sub = words[0]
+  const quiet = args.includes("--quiet")
+  const say = (l: string) => {
+    if (!quiet) io.out(l)
+  }
+  const unknown = args.find((a) => a.startsWith("-") && !FLAGS.has(a))
+  if (args.includes("--help") || args.includes("-h") || sub === "help") {
+    USAGE.forEach((l) => io.out(l))
+    return 0
+  }
+  if (unknown || words.length > 1) {
+    io.out(unknown ? `unknown option ${unknown}` : `unexpected "${words[1]}"`)
+    USAGE.forEach((l) => io.out(`usage: ${l}`))
+    return 2
+  }
+  const notSignedIn = "not signed in to the gateway: run `brain gateway login` first, then `brain dashboard`"
+  const send = async (counts: boolean): Promise<void> => {
+    // The notice goes where the person reads it: the output, or stderr when the output is asked to stay quiet.
+    noticeOnce(home, quiet ? io.err : io.out)
+    const { buildReport, countAndKeep } = await import("./report.ts")
+    const report = await buildReport(home, {
+      env,
+      ...(counts ? { counts: await countAndKeep(home, { timeoutMs: deps.countTimeoutMs ?? 20_000, ...(deps.readers ? { readers: deps.readers } : {}) }) } : {}),
+    })
+    const r = await sendReport(home, report, deps.fetchImpl ? { fetchImpl: deps.fetchImpl } : {})
+    say(r.ok ? `sent this machine's report to ${gatewayUrl(home)}: ${summary(report)}` : `could not send the report: ${r.why}; the dashboard keeps the last report it got`)
+  }
+
+  switch (sub) {
+    case undefined: {
+      if (!signedIn(home)) {
+        io.out(notSignedIn)
+        return 1
+      }
+      const off = sendingOff(home, env)
+      if (off) say(`reports are off (${off}): nothing was sent${readSettings(home).off ? "; `brain dashboard on` starts them again" : ""}`)
+      else await send(true)
+      if (args.includes("--no-open")) say(`the dashboard: ${DASHBOARD_URL}`)
+      else {
+        ;(deps.open ?? openInBrowser)(DASHBOARD_URL)
+        say(`opening ${DASHBOARD_URL}`)
+      }
+      return 0
+    }
+    case "push": {
+      // `--at <ms>`: a background push started by another command waits for its turn (send.ts), then reads the state.
+      const at = atAt >= 0 ? Number(args[atAt + 1]) : NaN
+      if (Number.isFinite(at)) await startScheduled(home, at, env)
+      if (!signedIn(home)) {
+        say(notSignedIn)
+        return quiet ? 0 : 1
+      }
+      const off = sendingOff(home, env)
+      if (off) {
+        say(`reports are off (${off}): nothing was sent`)
+        return 0
+      }
+      await send(false)
+      return 0
+    }
+    case "off":
+      updateSettings(home, (s) => {
+        s.off = true
+      })
+      say("reports are off: brain sends nothing from this machine to your 100xprompt account. The console keeps the last report until you remove this machine there; `brain dashboard on` starts them again.")
+      return 0
+    case "on": {
+      updateSettings(home, (s) => {
+        delete s.off
+      })
+      const notes = [sendingOff(home, env) ? "BRAIN_NO_REPORT is set here, so nothing is sent while it is" : "", signedIn(home) ? "" : "sign in first: brain gateway login"].filter(Boolean)
+      say(`reports are on: brain sends this machine's report after commands that change it, and with \`brain dashboard\`${notes.length ? ` (${notes.join("; ")})` : ""}.`)
+      return 0
+    }
+    case "status": {
+      const { gatewayState, machineName } = await import("./report.ts")
+      const { machineId } = await import("./state.ts")
+      const off = sendingOff(home, env)
+      const push = readCache(home).push ?? {}
+      const counts = readCache(home).counts
+      const email = gatewayState(home).email
+      const lines = [
+        `reports: ${off ? `off (${off})` : "on"}`,
+        `signed in: ${signedIn(home) ? `yes${typeof email === "string" && email ? `, as ${email}` : ""}` : "no (brain gateway login)"}`,
+        `sends to: ${reportUrl(home)}`,
+        `last sent: ${push.lastSentAt ? `${push.lastSentAt} (${ago(push.lastSentAt)})` : "never"}`,
+        ...(push.lastError && push.lastAttemptAt ? [`last attempt: ${push.lastAttemptAt} (${ago(push.lastAttemptAt)}) failed: ${push.lastError}`] : []),
+        ...(typeof push.pendingUntilMs === "number" && push.pendingUntilMs > Date.now() ? [`next: a report waits to go out at ${new Date(push.pendingUntilMs).toISOString()}`] : []),
+        `sessions counted: ${counts?.at ? `${counts.at} (${ago(counts.at)}; \`brain dashboard\` counts them again)` : "never (`brain dashboard` counts them)"}`,
+        `conversions logged: ${readConversions(home, 0).total}`,
+        `machine: ${machineName()} (${machineId(home)})`,
+        `view: ${DASHBOARD_URL}`,
+      ]
+      lines.forEach((l) => io.out(l))
+      return 0
+    }
+    default:
+      io.out(`unknown dashboard command "${sub}"`)
+      USAGE.forEach((l) => io.out(`usage: ${l}`))
+      return 2
+  }
+}

package/src/dashboard/conversions.ts

@@ -0,0 +1,170 @@
+// The conversion log: one line per session brain carried from one tool into another (`session continue` / `handoff`, not
+// dry runs), for the Brain view of the console. <home>/.brain/logs/conversions.jsonl (0600), append-only. What a line
+// holds is exactly a conversion of the dashboard report (docs/dashboard-contract.md): which tools, how, when, the chat's
+// title and its project FOLDER NAME. Never the chat text, never a full path.
+import { appendFileSync, chmodSync, existsSync, mkdirSync, readFileSync } from "node:fs"
+import { homedir } from "node:os"
+import { basename, join, resolve } from "node:path"
+import type { Way } from "../adapters/types.ts"
+import { redact } from "../memory/redact.ts"
+
+export const conversionLog = (home: string) => join(home, ".brain", "logs", "conversions.jsonl")
+
+export const TITLE_MAX = 200
+export const PROJECT_MAX = 120
+const LABEL_MAX = 80
+const WAYS: readonly Way[] = ["native", "import", "brief"]
+
+export interface Conversion {
+  /** Made when the conversion happened: the gateway drops a conversion it already has. */
+  id: string
+  at: string
+  from: string
+  fromLabel: string
+  to: string
+  toLabel: string
+  way: Way
+  title: string | null
+  /** The project folder's name only (basename), never its path. */
+  project: string | null
+  turns: number | null
+  /** Estimated tokens of the converted session. */
+  tokens: number | null
+  /** Big tool outputs were replaced by digests. */
+  lean: boolean
+}
+
+/** At most `n` UTF-16 units, never ending in half of a surrogate pair. */
+export function clip(s: string, n: number): string {
+  if (s.length <= n) return s
+  const cut = s.slice(0, n)
+  return /[\uD800-\uDBFF]$/.test(cut) ? cut.slice(0, -1) : cut
+}
+
+/** A title as it may be sent: one line, secrets taken out, at most 200 characters; null when there is none. */
+export function cleanTitle(t: unknown): string | null {
+  if (typeof t !== "string") return null
+  const one = redact(t.replace(/\s+/g, " ").trim())
+  return one ? clip(one, TITLE_MAX) : null
+}
+
+/** The project folder's name, from a folder path or a name; null for none, the root, or a home folder (not a project). */
+export function projectName(cwd: unknown, homes: string[] = []): string | null {
+  if (typeof cwd !== "string" || !cwd.trim()) return null
+  const p = cwd.trim()
+  if (p.includes("/") || p.includes("\\")) {
+    const full = resolve(p)
+    if (full === "/" || homes.some((h) => h && resolve(h) === full)) return null
+  }
+  const name = basename(p.replace(/[\\/]+$/, "")).split("\\").pop() ?? ""
+  return name ? clip(name, PROJECT_MAX) : null
+}
+
+const count = (n: unknown): number | null => (typeof n === "number" && Number.isFinite(n) && n >= 0 ? Math.floor(n) : null)
+const label = (s: unknown, fallback: string) => clip(typeof s === "string" && s.trim() ? s.trim() : fallback, LABEL_MAX)
+
+/** What `continue` knows when a writer has written: the tools, the way, and the source session's header and size. */
+export interface ConversionInput {
+  from: string
+  fromLabel: string
+  to: string
+  toLabel: string
+  way: Way
+  title?: string
+  /** The session's project folder (only its name is kept). */
+  cwd?: string
+  turns?: number
+  tokens?: number
+  lean: boolean
+  at?: string
+}
+
+/** "cursor" is what `continue --in` calls Cursor; everywhere else (readers, hooks, harnesses) it is "cursor-ide". */
+export const toolId = (tool: string) => (tool === "cursor" ? "cursor-ide" : tool)
+
+/** One line for the log, from what `continue` knows. */
+export function conversionOf(c: ConversionInput, homes: string[] = [process.env.BRAIN_HOME ?? "", process.env.HOME ?? "", homedir()]): Conversion {
+  return {
+    id: crypto.randomUUID(),
+    at: c.at ?? new Date().toISOString(),
+    from: toolId(c.from),
+    fromLabel: label(c.fromLabel, c.from),
+    to: toolId(c.to),
+    toLabel: label(c.toLabel.replace(/^the /, ""), c.to),
+    way: c.way,
+    title: cleanTitle(c.title),
+    project: projectName(c.cwd, homes),
+    turns: count(c.turns),
+    tokens: count(c.tokens),
+    lean: !!c.lean,
+  }
+}
+
+/** Appends one conversion. Never throws: a log must not break a conversion that already happened. */
+export function logConversion(home: string, c: ConversionInput): Conversion | undefined {
+  try {
+    const line = conversionOf(c)
+    const f = conversionLog(home)
+    mkdirSync(join(home, ".brain", "logs"), { recursive: true, mode: 0o700 })
+    const fresh = !existsSync(f)
+    appendFileSync(f, `${JSON.stringify(line)}\n`, { mode: 0o600 })
+    if (fresh) chmodSync(f, 0o600)
+    return line
+  } catch {
+    return undefined
+  }
+}
+
+const ISO = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/
+
+/** A line of the log as it may be sent, or undefined for a line that is not a conversion (a damaged or foreign line). */
+export function parseConversion(line: string): Conversion | undefined {
+  let v: any
+  try {
+    v = JSON.parse(line)
+  } catch {
+    return undefined
+  }
+  if (!v || typeof v !== "object" || typeof v.id !== "string" || !v.id || typeof v.at !== "string" || !ISO.test(v.at)) return undefined
+  if (typeof v.from !== "string" || !v.from || typeof v.to !== "string" || !v.to || !WAYS.includes(v.way)) return undefined
+  // Read back through the same filters it was written with: whatever is in the file, only these fields, clipped, leave.
+  return {
+    id: clip(v.id, 64),
+    at: v.at,
+    from: clip(v.from, LABEL_MAX),
+    fromLabel: label(v.fromLabel, v.from),
+    to: clip(v.to, LABEL_MAX),
+    toLabel: label(v.toLabel, v.to),
+    way: v.way,
+    title: cleanTitle(v.title),
+    project: projectName(v.project),
+    turns: count(v.turns),
+    tokens: count(v.tokens),
+    lean: v.lean === true,
+  }
+}
+
+/** Months (UTC, "YYYY-MM") counted in a report's totals.byMonth: the latest twelve that have any conversion. */
+export const MONTHS_KEPT = 12
+
+/** The newest `limit` conversions (newest first), how many the log holds in all, and how many per month (UTC). */
+export function readConversions(home: string, limit = 500): { list: Conversion[]; total: number; byMonth: Record<string, number> } {
+  let text = ""
+  try {
+    text = readFileSync(conversionLog(home), "utf8")
+  } catch {
+    return { list: [], total: 0, byMonth: {} }
+  }
+  const all: Conversion[] = []
+  for (const line of text.split("\n")) {
+    if (!line.trim()) continue
+    const c = parseConversion(line)
+    if (c) all.push(c)
+  }
+  // The file is in the order they happened; a sort by time keeps that for lines written by machines with a skewed clock.
+  const newest = all.map((c, i) => ({ c, i })).sort((a, b) => b.c.at.localeCompare(a.c.at) || b.i - a.i).map((x) => x.c)
+  const months = new Map<string, number>()
+  for (const c of all) months.set(c.at.slice(0, 7), (months.get(c.at.slice(0, 7)) ?? 0) + 1)
+  const byMonth = Object.fromEntries([...months].sort((a, b) => b[0].localeCompare(a[0])).slice(0, MONTHS_KEPT))
+  return { list: newest.slice(0, Math.max(0, limit)), total: all.length, byMonth }
+}

package/src/dashboard/report.ts

@@ -0,0 +1,261 @@
+// The report of this machine for the Brain view of the 100xprompt console, built exactly as docs/dashboard-contract.md
+// says: the machine, the coding tools present here (sessions, gateway, MCP tools, hooks), the gateway settings, memory
+// counts, and the conversions brain made. Summaries plus each chat's title and project folder name: never chat text, file
+// contents, full paths or keys.
+import { existsSync, readFileSync } from "node:fs"
+import { hostname } from "node:os"
+import { join } from "node:path"
+import type { Reader } from "../adapters/types.ts"
+import { toolLabel } from "../brief.ts"
+import { DEFAULT_MODEL, DEFAULT_ROUTE, type Env, type GatewaySettings, modelName, statePath } from "../gateway/common.ts"
+import { CONNECTORS, hasKey, installedHere } from "../gateway/connect.ts"
+import { HOOK_TOOLS, hookInstalled } from "../hooks.ts"
+import { MCP_TOOLS, statusMcp } from "../memory/mcp-install.ts"
+import { chittaCandidates, memoryDbPath, openMemory } from "../memory/store.ts"
+import { readOrgConfig } from "../org/config.ts"
+import { VERSION } from "../self.ts"
+import { clip, type Conversion, readConversions, toolId } from "./conversions.ts"
+import { machineId, readCache, type ToolCount, updateCache } from "./state.ts"
+
+export const SCHEMA = "brain-report/v1"
+/** The gateway takes at most 500 conversions and 512 KB; a report is cut to fit below that. */
+export const MAX_CONVERSIONS = 500
+export const MAX_BYTES = 500_000
+
+export interface Harness {
+  id: string
+  label: string
+  /** Sessions brain can read for it here; null when never counted (`brain dashboard` counts them). */
+  sessions: number | null
+  lastSessionAt: string | null
+  gateway: "connected" | "available" | "unsupported"
+  /** brain_recall / brain_expand installed in it; null when brain has no MCP installer for it. */
+  mcp: boolean | null
+  /** The session-start hook installed; null when brain has no hook for it. */
+  hooks: boolean | null
+}
+
+export interface BrainReport {
+  schema: typeof SCHEMA
+  sentAt: string
+  machine: { id: string; name: string; os: string; brainVersion: string }
+  harnesses: Harness[]
+  gateway: {
+    signedIn: boolean
+    email?: string
+    route: string
+    model: string
+    contextEdit: boolean
+    connected: Array<{ tool: string; label: string; since: string | null }>
+  }
+  memory: { available: true; projects: number; items: number } | { available: false }
+  conversions: Conversion[]
+  /** byMonth: conversions per month, UTC "YYYY-MM", the latest twelve months that have any. */
+  totals: { conversions: number; byMonth: Record<string, number> }
+}
+
+/** The computer's name: os.hostname() without ".local". */
+export const machineName = (h: string = hostname()) => clip(h.replace(/\.local\.?$/i, "").trim(), 80) || "this machine"
+
+const isoOrNull = (v: unknown): string | null => {
+  if (typeof v !== "string" && typeof v !== "number") return null
+  const t = typeof v === "number" ? v : Date.parse(v)
+  return Number.isFinite(t) ? new Date(t).toISOString() : null
+}
+
+interface GatewayState {
+  settings?: Partial<GatewaySettings>
+  email?: string
+  tools?: Record<string, { at?: string }>
+}
+
+/** <home>/.brain/gateway.json as `brain gateway` keeps it (read only here). */
+export function gatewayState(home: string): GatewayState {
+  try {
+    const s = JSON.parse(readFileSync(statePath(home), "utf8"))
+    return s && typeof s === "object" ? s : {}
+  } catch {
+    return {}
+  }
+}
+
+/** What the MCP installer calls a tool, as the readers (and so the report) call it. */
+const MCP_IDS: Record<string, string> = { cursor: "cursor-ide", gemini: "gemini-cli", vscode: "vscode-copilot" }
+const mcpToolId = (id: string) => MCP_IDS[id] ?? id
+
+async function withTimeout<T>(p: Promise<T>, ms: number): Promise<T | undefined> {
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const late = new Promise<undefined>((r) => {
+    timer = setTimeout(() => r(undefined), ms)
+  })
+  try {
+    return await Promise.race([p.catch(() => undefined), late])
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+/**
+ * Sessions per tool, from every reader at once, within `timeoutMs`; a reader that fails or takes longer is left out (its
+ * last count stays in the cache). Some readers copy a big database to read it, so this runs only for `brain dashboard`.
+ */
+export async function countSessions(home: string, o: { timeoutMs?: number; readers?: Reader[] } = {}): Promise<Record<string, ToolCount>> {
+  const readers = o.readers ?? (await import("../adapters/index.ts")).READERS
+  const out: Record<string, ToolCount> = {}
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const deadline = new Promise<"late">((r) => {
+    timer = setTimeout(r, o.timeoutMs ?? 20_000, "late" as const)
+  })
+  try {
+    await Promise.all(
+      readers.map(async (r) => {
+        const refs = await Promise.race([r.list(home).catch(() => undefined), deadline])
+        if (!refs || refs === "late") return
+        const id = toolId(r.tool)
+        const newest = refs.map((x) => isoOrNull(x.updatedAt)).filter((x): x is string => !!x).sort().pop() ?? null
+        const had = out[id]
+        out[id] = { sessions: (had?.sessions ?? 0) + refs.length, lastSessionAt: [had?.lastSessionAt, newest].filter((x): x is string => !!x).sort().pop() ?? null }
+      }),
+    )
+  } finally {
+    clearTimeout(timer)
+  }
+  return out
+}
+
+/** Counts sessions now and keeps the counts for later background reports (merged over the last ones). */
+export async function countAndKeep(home: string, o: { timeoutMs?: number; readers?: Reader[] } = {}): Promise<Record<string, ToolCount>> {
+  const fresh = await countSessions(home, o)
+  const c = updateCache(home, (c) => {
+    c.counts = { at: new Date().toISOString(), tools: { ...(c.counts?.tools ?? {}), ...fresh } }
+  })
+  return c.counts!.tools
+}
+
+async function memorySummary(home: string, env: Env): Promise<BrainReport["memory"]> {
+  try {
+    const org = env.BRAIN_ORG !== "off" && readOrgConfig(home)
+    // No store yet: say whether memory can be used, without creating one.
+    if (!org && !existsSync(memoryDbPath(home))) return chittaCandidates().some((f) => existsSync(f)) ? { available: true, projects: 0, items: 0 } : { available: false }
+    const mem = openMemory(home)
+    try {
+      const r = await withTimeout(
+        (async () => {
+          const s = await mem.status()
+          if (!s.available) return { available: false as const }
+          const projects = await mem.projects()
+          return { available: true as const, projects: projects.length, items: projects.reduce((n, p) => n + (Number(p.items) || 0), 0) }
+        })(),
+        5_000,
+      )
+      return r ?? { available: false }
+    } finally {
+      mem.close()
+    }
+  } catch {
+    return { available: false }
+  }
+}
+
+/** Whether a tool the MCP installer knows has run here (its config or folder exists), as the installer decides it. */
+function mcpToolHere(t: (typeof MCP_TOOLS)[number], home: string, env: Env): boolean {
+  if (t.id === "claude-code" && env.CLAUDE_CONFIG_DIR && existsSync(env.CLAUDE_CONFIG_DIR)) return true
+  return t.probe.some((p) => existsSync(join(home, p)))
+}
+
+/**
+ * Every coding tool brain knows (its readers, gateway connectors, MCP installer and hooks) that is present here: found by
+ * the connector's or the installer's probe, connected, with brain's MCP tools or hook in it, or with sessions counted.
+ */
+export async function harnesses(home: string, counts: Record<string, ToolCount> | undefined, env: Env = process.env): Promise<Harness[]> {
+  const { READERS } = await import("../adapters/index.ts")
+  const st = gatewayState(home)
+  const connected = st.tools && typeof st.tools === "object" ? st.tools : {}
+  let mcpInstalled = new Map<string, boolean>()
+  try {
+    mcpInstalled = new Map(statusMcp(home).map((c) => [mcpToolId(c.tool), c.action === "installed"]))
+  } catch {}
+  const hookOn = (id: string) => {
+    try {
+      return hookInstalled(id, home)
+    } catch {
+      return false
+    }
+  }
+  const known = new Map<string, { label: string; present: boolean }>()
+  const add = (id: string, label: string, present: boolean) => {
+    const k = known.get(id)
+    if (k) k.present ||= present
+    else known.set(id, { label, present })
+  }
+  for (const r of READERS) add(toolId(r.tool), r.label, (counts?.[toolId(r.tool)]?.sessions ?? 0) > 0)
+  for (const c of CONNECTORS) {
+    let here = false
+    try {
+      here = installedHere(c, home, env)
+    } catch {}
+    add(c.id, c.label, here || !!connected[c.id])
+  }
+  for (const t of MCP_TOOLS) add(mcpToolId(t.id), t.label, mcpToolHere(t, home, env) || mcpInstalled.get(mcpToolId(t.id)) === true)
+  for (const id of HOOK_TOOLS) add(id, toolLabel(id), hookOn(id))
+  const mcpIds = new Set(MCP_TOOLS.map((t) => mcpToolId(t.id)))
+  const connectorIds = new Set(CONNECTORS.map((c) => c.id))
+  return [...known.entries()]
+    .filter(([, k]) => k.present)
+    .map(([id, k]): Harness => ({
+      id,
+      label: clip(k.label, 80),
+      sessions: counts?.[id] ? counts[id]!.sessions : null,
+      lastSessionAt: counts?.[id]?.lastSessionAt ?? null,
+      gateway: connected[id] ? "connected" : connectorIds.has(id) ? "available" : "unsupported",
+      mcp: mcpIds.has(id) ? mcpInstalled.get(id) === true : null,
+      hooks: HOOK_TOOLS.includes(id) ? hookOn(id) : null,
+    }))
+    .sort((a, b) => a.label.localeCompare(b.label) || a.id.localeCompare(b.id))
+}
+
+/** The gateway part: signed in or not, the settings `brain gateway status` shows, and the tools connected to it. */
+export function gatewayPart(home: string): BrainReport["gateway"] {
+  const st = gatewayState(home)
+  const s = st.settings && typeof st.settings === "object" ? st.settings : {}
+  const label = (id: string) => CONNECTORS.find((c) => c.id === id)?.label ?? toolLabel(id)
+  return {
+    signedIn: hasKey(home),
+    ...(typeof st.email === "string" && st.email ? { email: clip(st.email, 200) } : {}),
+    route: typeof s.route === "string" && s.route ? s.route : DEFAULT_ROUTE,
+    model: modelName(typeof s.model === "string" && s.model ? s.model : DEFAULT_MODEL),
+    contextEdit: typeof s.contextEdit === "boolean" ? s.contextEdit : true,
+    connected: Object.entries(st.tools && typeof st.tools === "object" ? st.tools : {}).map(([tool, rec]) => ({ tool, label: clip(label(tool), 80), since: isoOrNull(rec?.at) })),
+  }
+}
+
+/**
+ * The whole report. Session counts are `counts` when given (`brain dashboard` just counted), else the last ones kept
+ * (null for a tool never counted); nothing here lists sessions, so a background report stays cheap.
+ */
+export async function buildReport(home: string, o: { counts?: Record<string, ToolCount>; now?: Date; env?: Env } = {}): Promise<BrainReport> {
+  const env = o.env ?? process.env
+  const counts = o.counts ?? readCache(home).counts?.tools
+  const { list, total, byMonth } = readConversions(home, MAX_CONVERSIONS)
+  return {
+    schema: SCHEMA,
+    sentAt: (o.now ?? new Date()).toISOString(),
+    machine: { id: machineId(home), name: machineName(), os: process.platform, brainVersion: VERSION },
+    harnesses: await harnesses(home, counts, env),
+    gateway: gatewayPart(home),
+    memory: await memorySummary(home, env),
+    conversions: list,
+    totals: { conversions: total, byMonth },
+  }
+}
+
+/** The report as it is sent: at most MAX_BYTES of JSON, the oldest conversions dropped first if it is bigger. */
+export function reportBody(r: BrainReport, maxBytes = MAX_BYTES): string {
+  let body = JSON.stringify(r)
+  let list = r.conversions
+  while (Buffer.byteLength(body) > maxBytes && list.length) {
+    list = list.slice(0, Math.floor(list.length * 0.9))
+    body = JSON.stringify({ ...r, conversions: list })
+  }
+  return body
+}