@100xprompt/brain 0.0.0-stage → 0.1.1

package/src/dashboard/send.ts

@@ -0,0 +1,213 @@
+// Sending the report (report.ts) to the person's 100xprompt account: POST <gateway>/api/brain/report with the brain's
+// gateway key, best effort, 10 s at most. docs/dashboard-contract.md has the rules:
+//   - only when signed in (`brain gateway login`), and not turned off (`brain dashboard off`, or BRAIN_NO_REPORT=1);
+//   - in the background after a command that changes what the report says, never slowing that command: the command starts
+//     a detached `brain dashboard push --quiet` and returns. At most one background push every 30 s: a command within 30 s
+//     of the last one schedules the next for 30 s after it, and a push already waiting covers later commands too, because a
+//     push reads the state when it runs;
+//   - the first time a report is about to go out, a notice says once what is sent and how to stop it.
+// This file stays cheap to import (every command that changes something loads it); report.ts is loaded only to send.
+import { CLI_PATH } from "../self.ts"
+import { DEFAULT_URL, type Env, readKey, statePath } from "../gateway/common.ts"
+import { readFileSync } from "node:fs"
+import { readCache, readSettings, updateCache, updateSettings } from "./state.ts"
+import type { BrainReport } from "./report.ts"
+
+/** Where the person sees what was sent. */
+export const DASHBOARD_URL = "https://100xprompt.com/dashboard?view=brain"
+export const REPORT_PATH = "/api/brain/report"
+export const SEND_TIMEOUT_MS = 10_000
+/** The least time between two background pushes. */
+export const REPORT_EVERY_MS = 30_000
+/** A waiting push that has not cleared its mark this long after its time has died: the mark is ignored. */
+const PENDING_STALE_MS = 60_000
+
+/** BRAIN_REPORT_EVERY_MS shortens or lengthens the 30 s between background pushes (tests use a short one). */
+export function reportEvery(env: Env = process.env): number {
+  const n = Number(env.BRAIN_REPORT_EVERY_MS)
+  return env.BRAIN_REPORT_EVERY_MS !== undefined && env.BRAIN_REPORT_EVERY_MS !== "" && Number.isFinite(n) && n >= 0 ? n : REPORT_EVERY_MS
+}
+
+/** The gateway address: the one `brain gateway connect --url` keeps in gateway.json, else https://proxy.100xprompt.com. */
+export function gatewayUrl(home: string): string {
+  try {
+    const u = JSON.parse(readFileSync(statePath(home), "utf8"))?.settings?.url
+    if (typeof u === "string" && u.trim()) return u.trim().replace(/\/+$/, "")
+  } catch {}
+  return DEFAULT_URL
+}
+
+export const reportUrl = (home: string) => `${gatewayUrl(home)}${REPORT_PATH}`
+
+/** The key goes over https only (plain http only to a gateway on this machine), as `brain gateway connect` allows. */
+export function safeUrl(url: string): boolean {
+  try {
+    const u = new URL(url)
+    if (u.username || u.password) return false
+    if (u.protocol === "https:") return true
+    return u.protocol === "http:" && ["127.0.0.1", "localhost", "[::1]"].includes(u.hostname)
+  } catch {
+    return false
+  }
+}
+
+export const signedIn = (home: string) => readKey(home).length > 0
+
+/** Why nothing is sent right now, or undefined when reports go out (signed in or not is checked separately). */
+export function sendingOff(home: string, env: Env = process.env): string | undefined {
+  const v = env.BRAIN_NO_REPORT
+  if (v !== undefined && v !== "" && v !== "0" && v.toLowerCase() !== "false") return "BRAIN_NO_REPORT is set"
+  if (readSettings(home).off) return "turned off with `brain dashboard off`"
+  return undefined
+}
+
+/** What the first-time notice says. */
+export const NOTICE = [
+  "brain: this machine now sends a report to your 100xprompt account, for the Brain view of the console",
+  `  (${DASHBOARD_URL}). It holds: this computer's name, OS and brain version; the coding tools found`,
+  "  here, their session counts, and which are connected to the gateway or have brain's MCP tools or hooks; your gateway",
+  "  settings and memory counts; and each chat brain moved between tools: when, from and to which tool, its title and its",
+  "  project folder's name. Never chat text, file contents, full paths or keys.",
+  "  Stop it: brain dashboard off",
+]
+
+/** Prints the notice the first time a report is about to go out, and remembers that it did. */
+export function noticeOnce(home: string, print: (line: string) => void): boolean {
+  if (readSettings(home).noticeShownAt) return false
+  NOTICE.forEach((l) => print(l))
+  try {
+    updateSettings(home, (s) => {
+      s.noticeShownAt = new Date().toISOString()
+    })
+  } catch {}
+  return true
+}
+
+export type SendResult = { ok: true; machines?: number } | { ok: false; why: string }
+
+/** POSTs the report. Never throws and never says the key; records when it went out (or why not) for `brain dashboard status`. */
+export async function sendReport(home: string, report: BrainReport, o: { fetchImpl?: typeof fetch; timeoutMs?: number } = {}): Promise<SendResult> {
+  const r = await post(home, report, o)
+  updateCache(home, (c) => {
+    const at = new Date().toISOString()
+    c.push = { ...c.push, lastAttemptAt: at }
+    if (r.ok) {
+      c.push.lastSentAt = at
+      delete c.push.lastError
+    } else c.push.lastError = r.why
+  })
+  return r
+}
+
+async function post(home: string, report: BrainReport, o: { fetchImpl?: typeof fetch; timeoutMs?: number }): Promise<SendResult> {
+  const key = readKey(home)
+  if (!key) return { ok: false, why: "not signed in (brain gateway login)" }
+  const url = reportUrl(home)
+  if (!safeUrl(url)) return { ok: false, why: `the gateway address ${gatewayUrl(home)} is not https; the key is never sent over it` }
+  const { reportBody } = await import("./report.ts")
+  const timeoutMs = o.timeoutMs ?? SEND_TIMEOUT_MS
+  try {
+    const res = await (o.fetchImpl ?? fetch)(url, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
+      body: reportBody(report),
+      // A redirect is not followed: it could carry the key to another host.
+      redirect: "manual",
+      signal: AbortSignal.timeout(timeoutMs),
+    })
+    if (res.ok) {
+      const j = (await res.json().catch(() => undefined)) as { machines?: unknown } | undefined
+      return { ok: true, ...(typeof j?.machines === "number" ? { machines: j.machines } : {}) }
+    }
+    const said = await res
+      .json()
+      .then((j: any) => (typeof j?.error === "string" ? j.error : typeof j?.error?.message === "string" ? j.error.message : typeof j?.reason === "string" ? j.reason : ""))
+      .catch(() => "")
+    const why =
+      res.status === 401 || res.status === 403 ? "the gateway refused the key (sign in again: brain gateway login)"
+      : res.status === 404 ? "this gateway does not take brain reports yet"
+      : res.status === 413 ? "the report was too big for the gateway"
+      : res.status === 429 ? "too many reports for now; the next one carries everything"
+      : res.status >= 300 && res.status < 400 ? `the gateway answered with a redirect (HTTP ${res.status}); not followed`
+      : `the gateway answered HTTP ${res.status}`
+    return { ok: false, why: said ? `${why}: ${String(said).slice(0, 200)}` : why }
+  } catch (e) {
+    const name = (e as Error)?.name
+    return { ok: false, why: name === "TimeoutError" || name === "AbortError" ? `the gateway did not answer within ${Math.round(timeoutMs / 1000)} s` : `could not reach ${gatewayUrl(home)}` }
+  }
+}
+
+/**
+ * When the next background push may run, given the last one: now, or 30 s after the last one started. undefined when one
+ * is already waiting (it reads the state when it runs, so it carries this change too).
+ */
+export function planPush(p: { lastStartMs?: number; pendingUntilMs?: number }, now: number, every = REPORT_EVERY_MS): { at: number } | undefined {
+  if (typeof p.pendingUntilMs === "number" && now < p.pendingUntilMs + PENDING_STALE_MS) return undefined
+  const last = typeof p.lastStartMs === "number" && p.lastStartMs <= now ? p.lastStartMs : -Infinity
+  return { at: Math.max(now, last + every) }
+}
+
+/**
+ * After a command that changed what the report says: starts `brain dashboard push --quiet` in a detached process and
+ * returns at once. Nothing at all when not signed in or turned off. Never throws.
+ */
+export function reportInBackground(home: string, o: { env?: Env; cli?: string; say?: (line: string) => void; now?: number } = {}): boolean {
+  const env = o.env ?? process.env
+  try {
+    if (!signedIn(home) || sendingOff(home, env)) return false
+    noticeOnce(home, o.say ?? ((l) => process.stderr.write(`${l}\n`)))
+    const plan = planPush(readCache(home).push ?? {}, o.now ?? Date.now(), reportEvery(env))
+    if (!plan) return false
+    updateCache(home, (c) => {
+      c.push = { ...c.push, pendingUntilMs: plan.at }
+    })
+    try {
+      const child = Bun.spawn([process.execPath, o.cli ?? CLI_PATH, "dashboard", "push", "--quiet", "--at", String(plan.at)], {
+        cwd: home,
+        detached: true,
+        stdio: ["ignore", "ignore", "ignore"],
+        env: { ...env, BRAIN_HOME: home },
+      })
+      child.unref()
+    } catch {
+      // Nothing started: the mark must not hold up the next command's push.
+      updateCache(home, (c) => {
+        if (c.push?.pendingUntilMs === plan.at) delete c.push.pendingUntilMs
+      })
+      return false
+    }
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** The start of a background push: waits for its time, then clears its mark, so a later command schedules the next. */
+export async function startScheduled(home: string, at: number, env: Env = process.env): Promise<void> {
+  const wait = Math.min(at - Date.now(), reportEvery(env) + 5_000)
+  if (wait > 0) await Bun.sleep(wait)
+  const now = Date.now()
+  updateCache(home, (c) => {
+    c.push = { ...c.push, lastStartMs: now }
+    if (typeof c.push.pendingUntilMs === "number" && c.push.pendingUntilMs <= Math.max(at, now)) delete c.push.pendingUntilMs
+  })
+}
+
+/**
+ * The last report before `brain gateway logout` forgets the key: the same snapshot, marked signed out, so the console does
+ * not go on showing this machine as signed in. Sent while the key is still there (after logout nothing can be sent),
+ * waited for briefly, best effort; nothing when reports are off or the person is not signed in.
+ */
+export async function reportSignedOut(home: string, o: { env?: Env; fetchImpl?: typeof fetch; timeoutMs?: number } = {}): Promise<SendResult | undefined> {
+  const env = o.env ?? process.env
+  if (sendingOff(home, env) || !readKey(home)) return undefined
+  try {
+    const { buildReport } = await import("./report.ts")
+    const report = await buildReport(home, { env })
+    report.gateway = { ...report.gateway, signedIn: false }
+    delete (report.gateway as { email?: string }).email
+    return await sendReport(home, report, { timeoutMs: o.timeoutMs ?? 3_000, ...(o.fetchImpl ? { fetchImpl: o.fetchImpl } : {}) })
+  } catch {
+    return undefined
+  }
+}

package/src/dashboard/state.ts

@@ -0,0 +1,95 @@
+// The small files the dashboard report keeps under <home>/.brain (all 0600, in a 0700 folder):
+//   machine.json          { id, createdAt }: this machine's random id, made once (the console tells machines apart by it)
+//   dashboard.json        the person's choice: { off?, noticeShownAt? }. Written only by the person's own commands, never
+//                         by a background push, so a push can never undo `brain dashboard off`.
+//   dashboard-cache.json  what brain works out or remembers by itself: the last session counts, and the push bookkeeping
+//                         (when the last report went out, a push that is waiting to run).
+// Every write re-reads the file first and changes only its own fields, then replaces the file atomically.
+import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs"
+import { dirname, join } from "node:path"
+
+export const brainDir = (home: string) => join(home, ".brain")
+export const machinePath = (home: string) => join(brainDir(home), "machine.json")
+export const settingsPath = (home: string) => join(brainDir(home), "dashboard.json")
+export const cachePath = (home: string) => join(brainDir(home), "dashboard-cache.json")
+
+export interface DashboardSettings {
+  /** `brain dashboard off`: nothing is sent. */
+  off?: boolean
+  /** When the first-time notice (what is sent, how to stop it) was shown. */
+  noticeShownAt?: string
+}
+
+export interface ToolCount {
+  sessions: number
+  lastSessionAt: string | null
+}
+
+export interface DashboardCache {
+  /** Sessions per tool id, from the last `brain dashboard` (counting is expensive: background reports reuse these). */
+  counts?: { at: string; tools: Record<string, ToolCount> }
+  push?: {
+    /** When the last background push started (epoch ms): the next one waits until 30 s after it. */
+    lastStartMs?: number
+    /** A background push is waiting to run at this time (epoch ms); it reads the state when it runs. */
+    pendingUntilMs?: number
+    lastAttemptAt?: string
+    lastSentAt?: string
+    /** Why the last attempt failed (cleared by a success). */
+    lastError?: string
+  }
+}
+
+function readJson<T extends object>(path: string): T {
+  try {
+    const v = JSON.parse(readFileSync(path, "utf8"))
+    return v && typeof v === "object" && !Array.isArray(v) ? (v as T) : ({} as T)
+  } catch {
+    return {} as T
+  }
+}
+
+/** Atomic write, 0600, in a 0700 <home>/.brain. */
+export function writePrivateJson(path: string, value: unknown) {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 })
+  const tmp = `${path}.${process.pid}.brain-tmp`
+  try {
+    writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 })
+    chmodSync(tmp, 0o600)
+    renameSync(tmp, path)
+  } finally {
+    rmSync(tmp, { force: true })
+  }
+}
+
+export const readSettings = (home: string): DashboardSettings => readJson<DashboardSettings>(settingsPath(home))
+export function updateSettings(home: string, change: (s: DashboardSettings) => void): DashboardSettings {
+  const s = readSettings(home)
+  change(s)
+  writePrivateJson(settingsPath(home), s)
+  return s
+}
+
+export const readCache = (home: string): DashboardCache => readJson<DashboardCache>(cachePath(home))
+/** Best effort: bookkeeping that cannot be written is not a reason to fail. */
+export function updateCache(home: string, change: (c: DashboardCache) => void): DashboardCache {
+  const c = readCache(home)
+  change(c)
+  try {
+    writePrivateJson(cachePath(home), c)
+  } catch {}
+  return c
+}
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+/** This machine's id: made once, kept in <home>/.brain/machine.json. A missing or damaged file gets a new one. */
+export function machineId(home: string): string {
+  const m = readJson<{ id?: unknown; createdAt?: unknown }>(machinePath(home))
+  if (typeof m.id === "string" && UUID.test(m.id)) return m.id
+  const id = crypto.randomUUID()
+  try {
+    writePrivateJson(machinePath(home), { id, createdAt: new Date().toISOString() })
+  } catch {}
+  return id
+}

package/src/fsutil.ts

@@ -0,0 +1,133 @@
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs"
+import { join, resolve } from "node:path"
+import type { Project } from "./session/types.ts"
+
+/** The home folder readers and writers work in: $BRAIN_HOME in tests, else the real one. */
+export function homeDir(): string {
+  return process.env.BRAIN_HOME ?? process.env.HOME ?? ""
+}
+
+/** macOS application-support folder for a home. */
+export const appSupport = (home: string) => join(home, "Library", "Application Support")
+
+export const exists = (p: string) => existsSync(p)
+
+export function isDir(p: string): boolean {
+  try {
+    return statSync(p).isDirectory()
+  } catch {
+    return false
+  }
+}
+
+export function mtime(p: string): string | undefined {
+  try {
+    return statSync(p).mtime.toISOString()
+  } catch {
+    return undefined
+  }
+}
+
+/** Directory entries, or none when the directory is missing or unreadable. */
+export function ls(dir: string): string[] {
+  try {
+    return readdirSync(dir)
+  } catch {
+    return []
+  }
+}
+
+/** Files under `dir` whose names match, depth-first, at most `depth` levels down. */
+export function findFiles(dir: string, match: (name: string) => boolean, depth = 4): string[] {
+  const out: string[] = []
+  const walk = (d: string, left: number) => {
+    for (const name of ls(d)) {
+      const p = join(d, name)
+      if (isDir(p)) {
+        if (left > 0) walk(p, left - 1)
+      } else if (match(name)) out.push(p)
+    }
+  }
+  walk(dir, depth)
+  return out
+}
+
+/** JSON from a file, or undefined when it is missing or not JSON. */
+export function readJson<T = unknown>(p: string): T | undefined {
+  try {
+    return JSON.parse(readFileSync(p, "utf8")) as T
+  } catch {
+    return undefined
+  }
+}
+
+/** Each line of a JSONL file parsed, skipping lines that are not JSON (a half-written last line, say); `bad` counts them. */
+export function readJsonl(p: string): { rows: Array<Record<string, any>>; bad: number } {
+  let text = ""
+  try {
+    text = readFileSync(p, "utf8")
+  } catch {
+    return { rows: [], bad: 0 }
+  }
+  const rows: Array<Record<string, any>> = []
+  let bad = 0
+  for (const line of text.split("\n")) {
+    if (!line.trim()) continue
+    try {
+      rows.push(JSON.parse(line))
+    } catch {
+      bad++
+    }
+  }
+  return { rows, bad }
+}
+
+/**
+ * Git remote, branch and commit for a folder, read from .git without running git; empty when it is not a
+ * repository. The walk up stops below the home folder: a dotfiles repository at ~/.git would otherwise make
+ * every project under home look like one project.
+ */
+export function gitInfo(cwd: string | undefined, home = homeDir()): Omit<Project, "cwd"> {
+  if (!cwd) return {}
+  const stop = home.replace(/\/+$/, "")
+  let dir = cwd
+  for (let i = 0; i < 30 && dir && dir !== "/" && dir !== stop; i++) {
+    const git = join(dir, ".git")
+    if (exists(git)) {
+      try {
+        // A worktree's .git is a file naming its git dir, absolute or relative to the worktree.
+        const gitDir = isDir(git) ? git : resolve(dir, readFileSync(git, "utf8").replace(/^gitdir:\s*/, "").trim())
+        const head = readFileSync(join(gitDir, "HEAD"), "utf8").trim()
+        const branch = head.startsWith("ref: refs/heads/") ? head.slice(16) : undefined
+        let commit: string | undefined = head.startsWith("ref:") ? undefined : head
+        if (branch) {
+          const ref = join(gitDir, "refs", "heads", branch)
+          commit = exists(ref) ? readFileSync(ref, "utf8").trim() : undefined
+        }
+        const config = exists(join(gitDir, "config")) ? readFileSync(join(gitDir, "config"), "utf8") : ""
+        const remote = config.match(/\[remote "origin"\][^[]*?url\s*=\s*(\S+)/)?.[1]
+        return { ...(remote ? { gitRemote: remote } : {}), ...(branch ? { gitBranch: branch } : {}), ...(commit ? { gitCommit: commit } : {}) }
+      } catch {
+        return {}
+      }
+    }
+    dir = dir.slice(0, dir.lastIndexOf("/"))
+  }
+  return {}
+}
+
+/** Whether a process with this exact name is running (a desktop app whose store must not be written while open). */
+export function isRunning(processName: string): boolean {
+  const p = Bun.spawnSync(["pgrep", "-x", processName], { stdout: "pipe", stderr: "pipe" })
+  return p.exitCode === 0
+}
+
+/** The first line of `<bin> --version`, or undefined when the binary is missing. */
+export function versionOf(bin: string): string | undefined {
+  try {
+    const p = Bun.spawnSync([bin, "--version"], { env: process.env, stdout: "pipe", stderr: "pipe", timeout: 10_000 })
+    return p.exitCode === 0 ? p.stdout.toString().trim().split("\n")[0] : undefined
+  } catch {
+    return undefined
+  }
+}

package/src/gateway/common.ts

@@ -0,0 +1,232 @@
+// What every gateway connector shares: the settings, the shape of a connector, where the key lives, and the helpers a
+// connector needs to describe its edits. connect.ts does the reading, writing, recording and undoing; a connector only
+// says which files it changes and to what (src/gateway/connectors/<tool>.ts).
+import { existsSync, readFileSync } from "node:fs"
+import { join } from "node:path"
+
+export type Json = Record<string, any>
+export type Env = Record<string, string | undefined>
+
+export const DEFAULT_URL = "https://proxy.100xprompt.com"
+export const DEFAULT_ROUTE = "flash"
+export const DEFAULT_MODEL = "gemini-3.8-flash"
+export const EDIT_HEADER = "x-100x-context-edit"
+
+/**
+ * What 100xprompt calls the models brain may connect a tool to, as the 100xprompt CLI shows them: tools are given the
+ * gateway's model id (that is what the gateway serves), and everything brain prints uses the product name.
+ */
+export const MODEL_NAMES: Record<string, string> = { "gemini-3.8-flash": "100xprompt Pro", "gemini-3.7-flash": "100xprompt Flash", "gemini-3.6-flash": "100xprompt Flash" }
+/** `--model pro` / `--model flash`: the product names, turned into the gateway's model ids. */
+export const MODEL_ALIASES: Record<string, string> = { pro: "gemini-3.8-flash", flash: "gemini-3.7-flash" }
+export const modelName = (id: string) => MODEL_NAMES[id] ?? id
+export const modelId = (given: string) => MODEL_ALIASES[given.trim().toLowerCase()] ?? given.trim()
+
+export interface GatewaySettings {
+  url: string
+  route: string
+  /** The gateway's model id (gemini-3.8-flash for 100xprompt Pro). Show it to people with modelName(). */
+  model: string
+  /** Send `x-100x-context-edit: on` (the gateway clears old tool results when that saves money). */
+  contextEdit: boolean
+}
+
+export const brainDir = (home: string) => join(home, ".brain")
+export const statePath = (home: string) => join(brainDir(home), "gateway.json")
+/** The gateway key, 0600, one line. A tool that can read a key from a file, a command or an env file should read it here. */
+export const keyPath = (home: string) => join(brainDir(home), "gateway.key")
+
+/** The stored key ("" when there is none: a dry run shows what would change without one). Never print it. */
+export function readKey(home: string): string {
+  try {
+    return readFileSync(keyPath(home), "utf8").trim()
+  } catch {
+    return ""
+  }
+}
+
+/**
+ * The gateway route's base address, e.g. https://proxy.100xprompt.com/flash. Under it the gateway serves, for every model:
+ *   /v1/chat/completions   OpenAI Chat Completions (Authorization: Bearer <key>)
+ *   /v1/responses          OpenAI Responses (Authorization: Bearer <key>)
+ *   /v1/messages           Anthropic Messages (x-api-key: <key>, or Authorization: Bearer)
+ *   /v1beta/models/<id>:generateContent and :streamGenerateContent   Gemini (x-goog-api-key: <key>)
+ * /v1/models answers 403 ("not served"), so a tool that insists on listing models first needs the model named in its config.
+ */
+export const routeUrl = (s: GatewaySettings) => `${s.url.replace(/\/+$/, "")}/${s.route}`
+
+/** Single-quoted for a POSIX shell. */
+export const shellQuote = (s: string) => `'${s.replace(/'/g, `'\\''`)}'`
+
+/** An env-overridable folder that only counts when it exists (CLAUDE_CONFIG_DIR, CODEX_HOME and the like). */
+export const dirFromEnv = (env: Env, name: string, fallback: string) => (env[name] && existsSync(env[name]!) ? env[name]! : fallback)
+
+/**
+ * A file format the core does not read itself (YAML, JSON with comments, a tool's own format): the connector reads and
+ * writes it. Keys are whatever the codec understands (for yamlTopLevel: a top-level key).
+ */
+export interface Codec {
+  /** undefined when the file can be changed safely; otherwise why not (the file is then left alone and nothing changes). */
+  check?(text: string): string | undefined
+  /** The value at `key` (undefined when absent), compared with what was written to tell whether it is still brain's. */
+  get(text: string, key: string): unknown
+  /** The whole text with `key` set to `value`, or removed when `value` is undefined. Everything else stays as it was. */
+  set(text: string, key: string, value: unknown): string
+}
+
+/**
+ *   json     plain JSON object; keys are paths with "/" (env/ANTHROPIC_BASE_URL). A file with comments is left alone.
+ *   toml     Codex's config.toml handling (top-level keys and the [model_providers.brain-gateway] table only).
+ *   dotenv   KEY=value lines.
+ *   custom   the edit's `codec` reads and writes it.
+ */
+export type Format = "json" | "toml" | "dotenv" | "custom"
+
+/** One file a connector changes, and the values it sets there. */
+export interface FileEdit {
+  path: string
+  format: Format
+  /** Required with format "custom". */
+  codec?: Codec
+  values: Record<string, unknown>
+  /** The file holds the key: it is made private (0600). */
+  holdsKey?: boolean
+  /** Keys among `values` whose value contains the key: never shown or recorded, and replaced when the person signs in again. */
+  secretKeys?: string[]
+}
+
+export interface Connector {
+  /** The id people pass to --tool, the same id brain uses for the tool's sessions where it has one. */
+  id: string
+  label: string
+  /** The main file it edits (shown in status), absolute. */
+  file(home: string, env: Env): string
+  /** Folders or files (relative to home) whose presence shows the tool has run here, besides the main file or its folder. */
+  probe: string[]
+  /** Every file it changes, with the values to set. Called often (status, dry runs, disconnect): no side effects. */
+  edits(home: string, s: GatewaySettings, env: Env): FileEdit[]
+  /** How this tool sends the key, for the free key check before connecting. */
+  authHeader: "x-api-key" | "authorization" | "x-goog-api-key"
+  /** What the person should know (shown on connect). */
+  notes: string[]
+}
+
+// ---- JSON paths --------------------------------------------------------------------------------------------------------
+
+const split = (k: string) => k.split("/")
+export function getAt(o: Json, key: string): unknown {
+  let cur: any = o
+  for (const p of split(key)) {
+    if (!cur || typeof cur !== "object" || !(p in cur)) return undefined
+    cur = cur[p]
+  }
+  return cur
+}
+export function setAt(o: Json, key: string, v: unknown) {
+  const ps = split(key)
+  let cur: any = o
+  for (const p of ps.slice(0, -1)) {
+    if (!cur[p] || typeof cur[p] !== "object" || Array.isArray(cur[p])) cur[p] = {}
+    cur = cur[p]
+  }
+  cur[ps[ps.length - 1]!] = v
+}
+export function deleteAt(o: Json, key: string) {
+  const ps = split(key)
+  const parents: any[] = [o]
+  let cur: any = o
+  for (const p of ps.slice(0, -1)) {
+    if (!cur || typeof cur !== "object") return
+    cur = cur[p]
+    parents.push(cur)
+  }
+  if (cur && typeof cur === "object") delete cur[ps[ps.length - 1]!]
+  // Drop objects this left empty (env: {} after the last key went), never the root.
+  for (let i = ps.length - 1; i >= 1; i--) {
+    const parent = parents[i - 1]
+    const child = parent?.[ps[i - 1]!]
+    if (child && typeof child === "object" && !Array.isArray(child) && !Object.keys(child).length) delete parent[ps[i - 1]!]
+  }
+}
+
+// ---- YAML, top-level keys only ------------------------------------------------------------------------------------------
+
+/**
+ * A YAML scalar or flow collection. A plain string is written as it is when YAML reads it back as the same string
+ * (`local-model`, `https://host/v1`); anything else is JSON (valid YAML), which keeps "on", "no" and "1.0" strings.
+ */
+// Words and numbers YAML 1.1 readers (PyYAML: Aider, Hermes) take for booleans, null or numbers, though Bun's YAML 1.2
+// reads them as strings: they are always quoted.
+const YAML11_SPECIAL = /^(?:y|n|yes|no|on|off|true|false|null|~|[-+]?\.?(?:inf|nan)|[-+]?(?:0x[0-9a-f_]+|0o?[0-7_]+|0b[01_]+|[0-9][0-9_:]*(?:\.[0-9_]*)?(?:e[-+]?[0-9]+)?))$/i
+
+function yamlValue(v: unknown): string {
+  if (typeof v === "string" && /^[A-Za-z0-9_./@-][A-Za-z0-9_./:@+=-]*$/.test(v) && !YAML11_SPECIAL.test(v)) {
+    try {
+      if ((Bun.YAML.parse(`k: ${v}`) as Json).k === v) return v
+    } catch {}
+  }
+  return JSON.stringify(v)
+}
+
+/** The ` # comment` at the end of a one-line YAML entry (a # after a space, outside quotes), with the spaces before it. */
+function yamlComment(line: string): string {
+  let quote: string | undefined
+  for (let i = line.indexOf(":") + 1; i > 0 && i < line.length; i++) {
+    const c = line[i]!
+    if (quote) {
+      if (c === "\\" && quote === '"') i++
+      else if (c === quote) quote = undefined
+    } else if (c === '"' || c === "'") quote = c
+    else if (c === "#" && /[ \t]/.test(line[i - 1]!)) {
+      let j = i
+      while (j > 0 && /[ \t]/.test(line[j - 1]!)) j--
+      return line.slice(j).trimEnd()
+    }
+  }
+  return ""
+}
+
+/**
+ * Edits top-level `key: value` entries of a YAML file and leaves every other line (comments included) exactly as it was.
+ * A value is written on one line (strings quoted; objects and lists in flow style, which YAML reads like block style). An
+ * existing entry is replaced together with its indented block, if it had one; an entry that is not there is added at the
+ * end. Keys are top-level names only (no paths).
+ */
+export const yamlTopLevel: Codec = {
+  check(text) {
+    if (!text.trim()) return undefined
+    if (/^---\s*$/m.test(text.replace(/^---\s*\n/, ""))) return "it holds more than one YAML document; left as it is"
+    try {
+      const v = Bun.YAML.parse(text)
+      if (v !== null && (typeof v !== "object" || Array.isArray(v))) return "it is not a YAML mapping; left as it is"
+    } catch {
+      return "it is not valid YAML; left as it is"
+    }
+    return undefined
+  },
+  get(text, key) {
+    if (!text.trim()) return undefined
+    const v = Bun.YAML.parse(text) as Json | null
+    return v && typeof v === "object" ? v[key] : undefined
+  },
+  set(text, key, value) {
+    const lines = text ? text.replace(/\n$/, "").split("\n") : []
+    const esc = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+    const head = new RegExp(`^(?:${esc}|"${esc}"|'${esc}')\\s*:(?:\\s|$)`)
+    const at = lines.findIndex((l) => head.test(l))
+    let end = at + 1
+    // The entry's block: the indented (or blank, or comment) lines that follow it, up to the next top-level line.
+    if (at >= 0) {
+      while (end < lines.length && (/^[ \t]/.test(lines[end]!) || lines[end]!.trim() === "" || /^[ \t]*-\s/.test(lines[end]!))) end++
+      // Blank lines and comments at the end of that run belong to whatever comes next, not to this entry.
+      while (end > at + 1 && (lines[end - 1]!.trim() === "" || /^\s*#/.test(lines[end - 1]!))) end--
+    }
+    // A one-line entry keeps its trailing comment, so a later restore gives the line back as it was.
+    const line = `${key}: ${yamlValue(value)}${at >= 0 && end === at + 1 ? yamlComment(lines[at]!) : ""}`
+    if (value === undefined) {
+      if (at >= 0) lines.splice(at, end - at)
+    } else if (at >= 0) lines.splice(at, end - at, line)
+    else lines.push(line)
+    return lines.length ? `${lines.join("\n")}\n` : ""
+  },
+}