@100xprompt/brain 0.1.4 → 0.1.6

package/src/service.ts

@@ -0,0 +1,490 @@
+// `brain service install | uninstall | status | run`: a brain that runs in the background, so a settings change made in the
+// dashboard reaches this computer by itself (docs/settings-contract.md, section 6).
+//
+//   install   macOS: a LaunchAgent (~/Library/LaunchAgents/com.100xprompt.brain.plist, `launchctl bootstrap gui/<uid>`);
+//             Linux: a systemd user unit (~/.config/systemd/user/brain.service, `systemctl --user enable --now`). Both start
+//             ~/.brain/bin/brain, a small script named brain (so the system's notice names brain, not bun) that runs the
+//             bun on the person's PATH with this brain's cli.ts. Never from a temporary bunx copy.
+//   run       the loop: every 60 s one exchange with the account (account.ts); when it took or applied anything, the report
+//             goes at once. Offline or failing: it waits longer each time (2, 4, 8, at most 10 minutes). One per home: a
+//             second waits until the first stops. It exits with RESTART_EXIT when the brain on disk is a newer version
+//             (launchd / systemd start the new one: they restart it only after that or a crash), and with 0 when brain was
+//             removed from disk (so nothing restarts it).
+// The person's environment comes from ~/.brain/env.json (their tool folders and opt-outs): written into the plist / unit,
+// and read again every round, so a brain started by launchd edits the files the person's tools read.
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs"
+import { dirname, join, resolve as resolvePath } from "node:path"
+import { writeAtomic } from "./fsutil.ts"
+import { holderGone, ownStart, withBrainLockSync } from "./lock.ts"
+import { CLI_PATH, isEphemeral, stableBun, VERSION } from "./self.ts"
+import { ENV_VARS, readRecordedEnv } from "./settings/env.ts"
+
+export const LABEL = "com.100xprompt.brain"
+export const plistPath = (home: string) => join(home, "Library", "LaunchAgents", `${LABEL}.plist`)
+export const unitPath = (home: string) => join(home, ".config", "systemd", "user", "brain.service")
+export const wrapperPath = (home: string) => join(home, ".brain", "bin", "brain")
+export const serviceStatePath = (home: string) => join(home, ".brain", "service.json")
+export const serviceLogPath = (home: string) => join(home, ".brain", "logs", "service.log")
+
+type Env = Record<string, string | undefined>
+type Io = { out(l: string): void }
+
+export interface ServiceDeps {
+  /** Runs launchctl / systemctl (tests replace it). */
+  run?: (argv: string[]) => { code: number; out: string }
+  platform?: string
+  uid?: number
+  /** The cli.ts the service starts (default: this brain's). */
+  cli?: string
+  bun?: string
+}
+
+const runCmd = (argv: string[]): { code: number; out: string } => {
+  try {
+    const p = Bun.spawnSync(argv, { stdout: "pipe", stderr: "pipe", timeout: 15_000 })
+    return { code: p.exitCode ?? 1, out: `${p.stdout.toString()}${p.stderr.toString()}` }
+  } catch (e) {
+    return { code: 1, out: String((e as Error).message) }
+  }
+}
+
+export interface ServiceState {
+  pid?: number
+  startedAt?: number
+  version?: string
+  lastRunAt?: string
+  lastOkAt?: string
+  lastError?: string
+}
+
+/** The exit code that has launchd / systemd start brain again (a newer brain is on disk). 0 leaves it stopped. */
+export const RESTART_EXIT = 75
+
+export function readServiceState(home: string): ServiceState {
+  try {
+    const j = JSON.parse(readFileSync(serviceStatePath(home), "utf8"))
+    return j && typeof j === "object" ? j : {}
+  } catch {
+    return {}
+  }
+}
+
+function writeServiceState(home: string, s: ServiceState) {
+  try {
+    mkdirSync(join(home, ".brain"), { recursive: true, mode: 0o700 })
+    writeAtomic(serviceStatePath(home), `${JSON.stringify(s, null, 1)}\n`, 0o600)
+  } catch {}
+}
+
+/** Whether the service is installed here (its plist or unit exists), and whether its loop is alive (cheap: no launchctl). */
+export function serviceState(home: string, platform: string = process.platform, every = loopEvery()): { installed: boolean; running: boolean; lastRunAt: string | null } {
+  const installed = existsSync(platform === "darwin" ? plistPath(home) : unitPath(home))
+  const s = readServiceState(home)
+  const alive = typeof s.pid === "number" && typeof s.startedAt === "number" && !holderGone({ pid: s.pid, startedAt: s.startedAt, at: "" })
+  // Its last round, or its start when it has had none yet (the first round can take its full 10 s).
+  const last = s.lastRunAt ? Date.parse(s.lastRunAt) : s.startedAt
+  const recent = typeof last === "number" && Number.isFinite(last) && Date.now() - last < Math.max(every, 60_000) * 12
+  return { installed, running: alive && recent, lastRunAt: s.lastRunAt ?? null }
+}
+
+/** The environment the service runs with: the person's recorded values, and where brain keeps its files. */
+function serviceEnv(home: string, env: Env): Record<string, string> {
+  const out: Record<string, string> = {}
+  for (const [k, v] of Object.entries(readRecordedEnv(home)?.vars ?? {})) if (typeof v === "string" && v) out[k] = v
+  // A brain kept somewhere other than the home folder (BRAIN_HOME) keeps it there in the background too.
+  if (env.BRAIN_HOME) out.BRAIN_HOME = env.BRAIN_HOME
+  if (!out.PATH && env.PATH) out.PATH = env.PATH
+  return out
+}
+
+const xml = (s: string) => s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&apos;" })[c]!)
+const shq = (s: string) => `'${s.replace(/'/g, `'\\''`)}'`
+
+export function plistText(wrapper: string, env: Record<string, string>, log: string): string {
+  const envXml = Object.entries(env)
+    .map(([k, v]) => `    <key>${xml(k)}</key>\n    <string>${xml(v)}</string>`)
+    .join("\n")
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${xml(wrapper)}</string>
+    <string>service</string>
+    <string>run</string>
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <dict>
+    <key>SuccessfulExit</key>
+    <false/>
+  </dict>
+  <key>ThrottleInterval</key>
+  <integer>30</integer>
+  <key>ProcessType</key>
+  <string>Background</string>
+  <key>LowPriorityIO</key>
+  <true/>
+  <key>EnvironmentVariables</key>
+  <dict>
+${envXml}
+  </dict>
+  <key>StandardOutPath</key>
+  <string>${xml(log)}</string>
+  <key>StandardErrorPath</key>
+  <string>${xml(log)}</string>
+</dict>
+</plist>
+`
+}
+
+/**
+ * A value inside systemd's double quotes: \ " and line breaks escaped, % doubled (a specifier otherwise), and in a command
+ * line $ doubled too (a variable otherwise).
+ */
+const sdq = (v: string, command = false) => {
+  let t = v.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n").replace(/\r/g, "\\r").replace(/%/g, "%%")
+  if (command) t = t.replace(/\$/g, "$$$$")
+  return `"${t}"`
+}
+
+export function unitText(wrapper: string, env: Record<string, string>, log: string): string {
+  const envLines = Object.entries(env)
+    .map(([k, v]) => `Environment=${sdq(`${k}=${v}`)}`)
+    .join("\n")
+  // The log path is taken as it is after "append:" (no quotes there): only % needs doubling, and a line break cannot be kept.
+  const logPath = log.replace(/%/g, "%%").replace(/[\r\n]/g, "")
+  return `[Unit]
+Description=brain by 100xprompt: keeps this computer's settings in step with your account
+
+[Service]
+ExecStart=${sdq(wrapper, true)} service run
+Restart=on-failure
+RestartSec=30
+StandardOutput=append:${logPath}
+StandardError=append:${logPath}
+${envLines}
+
+[Install]
+WantedBy=default.target
+`
+}
+
+/** `brain service install`: the wrapper, the plist or unit, and the system told to start it. */
+export function installService(home: string, io: Io, env: Env = process.env, deps: ServiceDeps = {}): number {
+  const platform = deps.platform ?? process.platform
+  if (platform !== "darwin" && platform !== "linux") {
+    io.out("brain service: not on this system yet (macOS and Linux only); run `brain sync` to take changes made in the dashboard")
+    return 1
+  }
+  const cli = deps.cli ?? CLI_PATH
+  if (isEphemeral(cli)) {
+    io.out("brain service: this brain is a temporary bunx copy, which a reboot or cache clean removes; install brain first: bun add -g @100xprompt/brain")
+    return 1
+  }
+  // launchd and systemd read the real home's folders: a brain kept elsewhere (BRAIN_HOME, used by tests) cannot have one.
+  if (env.BRAIN_HOME && env.HOME && resolvePath(env.BRAIN_HOME) !== resolvePath(env.HOME)) {
+    io.out("brain service: BRAIN_HOME points away from your home folder, and the system starts background services only from your home's; run it without BRAIN_HOME")
+    return 1
+  }
+  const run = deps.run ?? runCmd
+  const bun = deps.bun ?? stableBun()
+  const wrapper = wrapperPath(home)
+  const vars = serviceEnv(home, env)
+  const file = platform === "darwin" ? plistPath(home) : unitPath(home)
+  // A script an earlier install left is kept when this one fails: a loaded service still starts it.
+  const hadWrapper = existsSync(wrapper)
+  try {
+    mkdirSync(dirname(wrapper), { recursive: true, mode: 0o700 })
+    mkdirSync(dirname(serviceLogPath(home)), { recursive: true, mode: 0o700 })
+    // Named brain, so the system's "background item added" notice says brain; it only starts this brain. A brain (or bun)
+    // removed from disk ends it quietly: exit 0, which the system does not restart.
+    writeAtomic(
+      wrapper,
+      `#!/bin/sh\n# brain's background service (brain service install). It runs this brain; brain service uninstall removes it.\n[ -f ${shq(cli)} ] && command -v ${shq(bun)} >/dev/null 2>&1 || exit 0\nexec ${shq(bun)} ${shq(cli)} "$@"\n`,
+      0o755,
+    )
+    mkdirSync(dirname(file), { recursive: true })
+    writeFileSync(file, platform === "darwin" ? plistText(wrapper, vars, serviceLogPath(home)) : unitText(wrapper, vars, serviceLogPath(home)), { mode: 0o644 })
+  } catch (e) {
+    if (!hadWrapper)
+      try {
+        rmSync(wrapper, { force: true })
+      } catch {}
+    const err = e as NodeJS.ErrnoException
+    const why = err?.code === "EACCES" || err?.code === "EPERM" ? "permission denied" : String(err?.message ?? e).slice(0, 200)
+    // The file or folder that failed, as the error names it (the wrapper's folder, the log's, LaunchAgents...).
+    const at = typeof err?.path === "string" ? err.path : file
+    io.out(`brain service: could not write ${at} (${why}); check that you own ${dirname(at)} (sudo chown $USER ${dirname(at)}), then run brain service install again`)
+    return 1
+  }
+  if (platform === "darwin") {
+    const uid = deps.uid ?? process.getuid?.() ?? 501
+    // Loaded afresh: an older one (another version, other environment) goes first.
+    run(["launchctl", "bootout", `gui/${uid}/${LABEL}`])
+    const r = run(["launchctl", "bootstrap", `gui/${uid}`, file])
+    if (r.code !== 0) {
+      io.out(`brain service: macOS did not start it (launchctl: ${r.out.trim().slice(0, 200) || `exit ${r.code}`}); the file is at ${file}`)
+      return 1
+    }
+  } else {
+    run(["systemctl", "--user", "daemon-reload"])
+    const r = run(["systemctl", "--user", "enable", "brain.service"])
+    // Restarted, not just started: an install again (another brain, other environment) takes effect at once.
+    const r2 = r.code === 0 ? run(["systemctl", "--user", "restart", "brain.service"]) : r
+    if (r2.code !== 0) {
+      io.out(`brain service: systemd did not start it (systemctl: ${r2.out.trim().slice(0, 200) || `exit ${r2.code}`}); the unit is at ${file}`)
+      return 1
+    }
+  }
+  io.out("brain service: installed and started. Every minute it takes changes made in your dashboard and applies them here.")
+  io.out(`  log: ${serviceLogPath(home)}; stop it: brain service uninstall`)
+  return 0
+}
+
+export function uninstallService(home: string, io: Io, deps: ServiceDeps = {}): number {
+  const platform = deps.platform ?? process.platform
+  const run = deps.run ?? runCmd
+  let had = false
+  if (platform === "darwin") {
+    const uid = deps.uid ?? process.getuid?.() ?? 501
+    if (existsSync(plistPath(home))) {
+      had = true
+      run(["launchctl", "bootout", `gui/${uid}/${LABEL}`])
+      rmSync(plistPath(home), { force: true })
+    }
+  } else if (platform === "linux" && existsSync(unitPath(home))) {
+    had = true
+    run(["systemctl", "--user", "disable", "--now", "brain.service"])
+    rmSync(unitPath(home), { force: true })
+    run(["systemctl", "--user", "daemon-reload"])
+  }
+  rmSync(wrapperPath(home), { force: true })
+  io.out(had ? "brain service: stopped and removed; `brain sync` (or brain status) still takes dashboard changes by hand" : "brain service: not installed here")
+  return 0
+}
+
+const ago = (iso?: string) => {
+  const t = iso ? Date.parse(iso) : NaN
+  if (!Number.isFinite(t)) return "never"
+  const s = Math.max(0, Math.round((Date.now() - t) / 1000))
+  return s < 90 ? `${s}s ago` : s < 5400 ? `${Math.round(s / 60)}m ago` : `${Math.round(s / 3600)}h ago`
+}
+
+export function serviceStatusLines(home: string, platform: string = process.platform): string[] {
+  if (platform !== "darwin" && platform !== "linux") return ["service: not on this system yet (brain sync takes the dashboard's changes)"]
+  const st = serviceState(home, platform)
+  const s = readServiceState(home)
+  if (!st.installed) return ["service: not installed (brain service install: dashboard changes then apply by themselves)"]
+  return [
+    `service: installed, ${st.running ? `running (version ${s.version ?? "?"}, last round ${ago(s.lastRunAt)})` : "not running right now"}`,
+    ...(s.lastError ? [`  the last round failed: ${s.lastError}`] : []),
+    `  log: ${serviceLogPath(home)}`,
+  ]
+}
+
+// ---- the loop -------------------------------------------------------------------------------------------------------------
+
+/** BRAIN_SERVICE_EVERY_MS: the time between rounds (tests use a short one). */
+export function loopEvery(env: Env = process.env): number {
+  const n = Number(env.BRAIN_SERVICE_EVERY_MS)
+  return env.BRAIN_SERVICE_EVERY_MS && Number.isFinite(n) && n >= 10 ? n : 60_000
+}
+
+/** The wait after `failures` failed rounds in a row: 1, 2, 4, 8 times the round, at most 10 minutes. */
+export const backoff = (every: number, failures: number) => (failures <= 0 ? every : Math.min(Math.max(every * 2 ** failures, every), Math.max(every, 600_000)))
+
+/** The version of the brain on disk now (a `bun add -g` while the service runs replaces it). */
+function versionOnDisk(cli: string): string | undefined {
+  try {
+    return JSON.parse(readFileSync(join(dirname(cli), "..", "package.json"), "utf8")).version
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * The person's recorded environment, applied to this process: what their shell has now (a tool folder or opt-out they
+ * dropped is dropped here too, whatever the plist or unit started this process with). PATH stays when none is recorded.
+ */
+export function refreshEnv(home: string, env: Env = process.env) {
+  const rec = readRecordedEnv(home)
+  if (!rec) return
+  for (const k of ENV_VARS) {
+    const v = rec.vars[k]
+    if (typeof v === "string" && v) env[k] = v
+    else if (k !== "PATH") delete env[k]
+  }
+}
+
+export interface LoopOptions {
+  /** Stop after this many rounds (tests). */
+  rounds?: number
+  /** How the person is asked about a move from the dashboard (tests; else a dialog, moves.ts). */
+  ask?: import("./moves.ts").Ask
+  env?: Env
+  fetchImpl?: typeof fetch
+  say?: (line: string) => void
+  cli?: string
+}
+
+type Turn = { ours: true } | { ours: false; pid: number }
+
+/**
+ * This loop's turn for the home, read, judged and written under the brain lock (two loops starting at once never both
+ * run): another live loop keeps it; otherwise `state` is written as this loop's. Called every round, so a loop that lost
+ * its turn stops exchanging.
+ */
+function keepTurn(home: string, state: ServiceState, every: number): Turn {
+  return withBrainLockSync(
+    home,
+    () => {
+      const cur = readServiceState(home)
+      const mine = cur.pid === state.pid && cur.startedAt === state.startedAt
+      // Another loop has the turn while its process lives and it has run a round lately (as serviceState judges running):
+      // a process id reused by something else, where its start cannot be told (no ps), never holds it for good.
+      const last = cur.lastRunAt ? Date.parse(cur.lastRunAt) : cur.startedAt
+      const lately = typeof last === "number" && Number.isFinite(last) && Date.now() - last < Math.max(every, 60_000) * 12
+      if (!mine && lately && typeof cur.pid === "number" && typeof cur.startedAt === "number" && cur.pid !== process.pid && !holderGone({ pid: cur.pid, startedAt: cur.startedAt, at: "" }))
+        return { ours: false, pid: cur.pid }
+      writeServiceState(home, state)
+      return { ours: true }
+    },
+    { what: "the background service's turn" },
+  )
+}
+
+/**
+ * `brain service run`: the loop. Returns when it should stop: the brain on disk changed ("updated"), brain was removed
+ * from disk ("gone"), or (tests) after `rounds` ("another" when another loop had the home all along). A round that fails
+ * in any way is a failed round, never the end of the process.
+ */
+export async function runService(home: string, o: LoopOptions = {}): Promise<"stopped" | "another" | "updated" | "gone"> {
+  const env = o.env ?? process.env
+  const say = o.say ?? ((l: string) => process.stdout.write(`${new Date().toISOString()} ${l}\n`))
+  const cli = o.cli ?? CLI_PATH
+  // Recorded as this process judges itself (lock.ts), so its own reports say it runs.
+  const state: ServiceState = { pid: process.pid, startedAt: ownStart(), version: VERSION }
+  say(`brain service ${VERSION} started`)
+  const { exchange } = await import("./settings/account.ts")
+  const { sendingOff, sendReport, canReport } = await import("./dashboard/send.ts")
+  let failures = 0
+  let waiting: number | undefined
+  let everOurs = false
+  for (let round = 1; ; round++) {
+    let wait = loopEvery(env)
+    try {
+      refreshEnv(home, env)
+      // Gone twice, 2 s apart: `bun add -g` replaces the package with cli.ts missing for a few milliseconds.
+      if (!existsSync(cli) && (await Bun.sleep(2_000), !existsSync(cli))) {
+        say("brain is no longer on this computer: this service stops (brain service uninstall removes what is left)")
+        return "gone"
+      }
+      const now = versionOnDisk(cli)
+      if (now && now !== VERSION) {
+        say(`brain on disk is now ${now}: this ${VERSION} stops, and the system starts the new one`)
+        if (everOurs) keepTurn(home, { ...state, lastRunAt: new Date().toISOString() }, loopEvery(env))
+        return "updated"
+      }
+      const turn = keepTurn(home, state, loopEvery(env))
+      if (!turn.ours) {
+        if (waiting !== turn.pid) say(`another brain service runs for this home (process ${turn.pid}); this one waits until it stops`)
+        waiting = turn.pid
+        if (o.rounds && round >= o.rounds) return everOurs ? "stopped" : "another"
+        await Bun.sleep(wait)
+        continue
+      }
+      if (waiting !== undefined) say("the other brain service stopped: this one takes over")
+      waiting = undefined
+      everOurs = true
+      const x = await exchange(home, { env, timeoutMs: 10_000, ...(o.fetchImpl ? { fetchImpl: o.fetchImpl } : {}) })
+      const at = new Date().toISOString()
+      if (!x.paired) {
+        state.lastRunAt = at
+        delete state.lastError
+      } else if (x.ok) {
+        failures = 0
+        Object.assign(state, { lastRunAt: at, lastOkAt: at })
+        delete state.lastError
+      } else {
+        failures++
+        Object.assign(state, { lastRunAt: at, lastError: x.why ?? "unknown" })
+        say(`round failed: ${x.why}`)
+      }
+      // Written before the report: the report says this loop runs.
+      keepTurn(home, state, loopEvery(env))
+      let moved = 0
+      if (x.ok) {
+        // Moves asked from the dashboard (moves.ts, docs/sessions-contract.md): as moves.fromDashboard says (ask first).
+        try {
+          const { processMoves } = await import("./moves.ts")
+          const mv = await processMoves(home, { ...(o.fetchImpl ? { fetchImpl: o.fetchImpl } : {}), ...(o.ask ? { ask: o.ask } : {}), say })
+          moved = mv.done + mv.refused + mv.failed + mv.pending
+        } catch {}
+        // The session list when it changed (looked at no more than every 5 minutes), and at once after a move.
+        try {
+          const { sendSessions } = await import("./dashboard/sessions.ts")
+          const sent = await sendSessions(home, { env, force: moved > 0, ...(o.fetchImpl ? { fetchImpl: o.fetchImpl } : {}) })
+          if (sent.sent) say(`sent the session list (${sent.total} sessions)`)
+        } catch {}
+      }
+      if (x.ok && (x.received.length || x.applied.length || moved)) {
+        if (x.received.length || x.applied.length) say(`took ${x.received.length} change(s) from your account, applied ${x.applied.length}`)
+        // The dashboard sees the result at once.
+        if (canReport(home) && !sendingOff(home, env)) {
+          try {
+            const { buildReport } = await import("./dashboard/report.ts")
+            const r = await sendReport(home, await buildReport(home, { env }), o.fetchImpl ? { fetchImpl: o.fetchImpl } : {})
+            if (!r.ok) say(`report not sent: ${r.why}`)
+          } catch {}
+        }
+      }
+      wait = backoff(loopEvery(env), failures)
+    } catch (e) {
+      // The brain lock busy for long, a disk that is full, anything else: this round failed, the loop goes on.
+      failures++
+      state.lastRunAt = new Date().toISOString()
+      state.lastError = `the round stopped: ${String((e as Error)?.message ?? e).slice(0, 200)}`
+      say(state.lastError)
+      try {
+        if (everOurs) keepTurn(home, state, loopEvery(env))
+      } catch {}
+      wait = backoff(loopEvery(env), failures)
+    }
+    if (o.rounds && round >= o.rounds) return "stopped"
+    await Bun.sleep(wait)
+  }
+}
+
+// ---- the command ---------------------------------------------------------------------------------------------------------
+
+const USAGE = [
+  "brain service install     run brain in the background, so changes made in your dashboard apply here by themselves",
+  "brain service uninstall   stop it and remove it",
+  "brain service status      whether it is installed and running, and its last round",
+]
+
+export async function serviceCommand(args: string[], home: string, io: Io = { out: (l) => console.log(l) }): Promise<number> {
+  const sub = args[0]
+  switch (sub) {
+    case "install":
+      return installService(home, io)
+    case "uninstall":
+      return uninstallService(home, io)
+    case "status":
+    case undefined:
+      serviceStatusLines(home).forEach((l) => io.out(l))
+      return 0
+    case "run":
+      // Only a newer brain on disk (or a crash) has the system start it again; brain removed from disk stays stopped.
+      return (await runService(home)) === "updated" ? RESTART_EXIT : 0
+    default:
+      io.out(`unknown service command "${sub}"`)
+      USAGE.forEach((l) => io.out(`usage: ${l}`))
+      return 2
+  }
+}

package/src/session/open.ts

@@ -0,0 +1,82 @@
+// `brain session open <id>`: a session opened in its own tool, in its own folder: the tool's resume command, as brain's
+// writers print it after a move (src/adapters/*/writer.ts). The dashboard shows `brain session open <id>` for every
+// session, so it needs no path and no tool's own syntax (docs/sessions-contract.md, section 3).
+import { existsSync } from "node:fs"
+import type { SessionRef } from "../adapters/types.ts"
+import { LAUNCHER_NAME, launcherApp } from "../gateway/connectors/antigravity.ts"
+
+/** A word for sh: as it is when it holds nothing the shell reads, else in single quotes (as the writers quote). */
+export const shellQuote = (s: string) => (/^[\w./@%+=:,-]+$/.test(s) ? s : `'${s.replace(/'/g, `'\\''`)}'`)
+
+type Resume = (id: string, cwd: string) => string
+
+/** Terminal tools, by brain's reader id: the command that reopens session `id` (run in the session's folder). */
+const IN_FOLDER: Record<string, Resume> = {
+  "claude-code": (id) => `claude --resume ${shellQuote(id)}`,
+  codex: (id) => `codex resume ${shellQuote(id)}`,
+  "gemini-cli": (id) => `gemini --resume ${shellQuote(id)}`,
+  "copilot-cli": (id) => `copilot --resume ${shellQuote(id)}`,
+  opencode: (id) => `opencode --session ${shellQuote(id)}`,
+  aider: () => "aider --restore-chat-history",
+  "amazon-q-cli": () => "q chat --resume",
+  codebuff: (id) => `codebuff --continue ${shellQuote(id)}`,
+  crush: (id) => `crush --session ${shellQuote(id)}`,
+  "factory-droid": (id) => `droid --resume ${shellQuote(id)}`,
+  goose: (id) => `goose session --resume --session-id ${shellQuote(id)} --history`,
+  "grok-cli": (id) => `grok --resume ${shellQuote(id)}`,
+  "iflow-cli": (id) => `iflow --resume ${shellQuote(id)}`,
+  "kimi-code": (id) => `kimi --session ${shellQuote(id)}`,
+  "mistral-vibe": (id) => `vibe --resume ${shellQuote(id)}`,
+  openhands: (id) => `openhands --resume ${shellQuote(id)}`,
+  "qoder-cli": (id) => `qodercli --resume ${shellQuote(id)}`,
+  "qwen-code": (id) => `qwen --resume ${shellQuote(id)}`,
+  "tabnine-cli": (id) => `tabnine --resume ${shellQuote(id)}`,
+  antigravity: (id) => `agy --conversation ${shellQuote(id)}`,
+  devin: (id) => `devin --resume ${shellQuote(id)}`,
+  omp: (id) => `omp --resume ${shellQuote(id)}`,
+}
+
+/** Desktop apps: opened on the session's folder, where the person picks the session from the app's history. */
+const APPS: Record<string, (cwd: string) => string | undefined> = {
+  // The Claude app opens on its own sessions (the Code tab): no folder to give it.
+  "claude-desktop": () => (process.platform === "darwin" ? "open -a Claude" : undefined),
+  "codex-desktop": () => (process.platform === "darwin" ? "open -a Codex" : undefined),
+  "cursor-ide": (cwd) => (process.platform === "darwin" ? `open -a Cursor ${shellQuote(cwd)}` : `cursor ${shellQuote(cwd)}`),
+  "vscode-copilot": (cwd) => `code ${shellQuote(cwd)}`,
+  zed: (cwd) => `zed ${shellQuote(cwd)}`,
+  void: (cwd) => (process.platform === "darwin" ? `open -a Void ${shellQuote(cwd)}` : undefined),
+}
+
+export type OpenPlan = { command: string; note?: string } | { none: string }
+
+/** How session `ref` is opened again where it is, or why brain cannot do that for its tool. */
+/** Antigravity's IDE app on this computer, when there is one (macOS: its name has changed between releases). */
+function antigravityApp(): string | undefined {
+  if (process.platform !== "darwin") return undefined
+  return ["Antigravity IDE", "Antigravity"].find((n) => existsSync(`/Applications/${n}.app`))
+}
+
+export function openPlan(ref: SessionRef, label: string = ref.tool, home?: string): OpenPlan {
+  const cwd = ref.cwd
+  // Antigravity on the 100xprompt gateway (brain gateway connect --tool antigravity): only its launcher starts it with the
+  // gateway's models, so the session is opened there (the CLI, started from a shell, would use Google's).
+  if (ref.tool === "antigravity" && home && process.platform === "darwin" && existsSync(launcherApp(home)))
+    return { command: `open -a ${shellQuote(LAUNCHER_NAME)}`, note: `then pick "${ref.title ?? ref.sourceId}" in its Agent Manager` }
+  // Antigravity: its CLI reopens a conversation by id; without the CLI, the IDE app opens and the person picks it.
+  if (ref.tool === "antigravity" && !Bun.which("agy")) {
+    const app = antigravityApp()
+    if (app) return { command: `open -a ${shellQuote(app)}`, note: `then pick "${ref.title ?? ref.sourceId}" in its Agent Manager` }
+  }
+  const resume = IN_FOLDER[ref.tool]
+  if (resume) {
+    const cmd = resume(ref.sourceId, cwd ?? "")
+    return cwd ? { command: `cd ${shellQuote(cwd)} && ${cmd}` } : { command: cmd, note: `run it in the session's project folder (${label} did not record it)` }
+  }
+  const app = APPS[ref.tool]
+  // Desktop apps open on their own sessions: no folder to give them.
+  const noFolder = ref.tool === "claude-desktop" || ref.tool === "codex-desktop"
+  const appCmd = app && (cwd || noFolder) ? app(cwd ?? "") : undefined
+  const where = ref.tool === "claude-desktop" ? "in the Code tab's sessions" : ref.tool === "codex-desktop" ? "in its threads" : `from ${label}'s chat history`
+  if (appCmd) return { command: appCmd, note: `then pick "${ref.title ?? ref.sourceId}" ${where}` }
+  return { none: `brain can't reopen ${label} sessions by itself: open ${label}${cwd ? ` in ${cwd}` : ""} and pick "${ref.title ?? ref.sourceId}" from its history (or move it: brain session continue ${ref.tool}:${ref.sourceId} --in <tool>)` }
+}