@100xprompt/brain 0.1.5 → 0.1.6

package/src/moves.ts

@@ -0,0 +1,402 @@
+// Moves asked from the dashboard (docs/sessions-contract.md, sections 2-3): "move this session to that tool", by ids only.
+// Each round the background service takes the computer's waiting moves and, one at a time:
+//   1. claims it (`asking`): from then on the dashboard cannot cancel it and no other round takes it again;
+//   2. finds the session here by its exact id (never a shortened one), and checks the target is a tool brain can write;
+//   3. as `moves.fromDashboard` says (ask by default): asks the person on this computer, showing the session brain found
+//      (its own title, folder and tool: never what the website called it), moves without asking, or refuses;
+//   4. moves it as `brain session continue <id> --in <tool> --no-open` would, and tells the account how it went (a result
+//      that could not be sent is kept and sent again next round).
+// Where there is no way to ask (no desktop), the move waits here for `brain moves approve <id>`. Nothing the website sends
+// is ever run as a command.
+import { readFileSync } from "node:fs"
+import { basename, join } from "node:path"
+import type { SessionRef, Way } from "./adapters/types.ts"
+import { gatewayUrl, safeUrl } from "./dashboard/send.ts"
+import { brainDir, machineId, readMachineToken, writePrivateJson } from "./dashboard/state.ts"
+import { withBrainLockSync } from "./lock.ts"
+import { cleanText } from "./settings/catalog.ts"
+import { type MovesSetting, movesSetting } from "./settings/values.ts"
+
+export const MOVES_PATH = "/api/brain/moves"
+const WAYS: Way[] = ["native", "import", "brief"]
+// biome-ignore lint/suspicious/noControlCharactersInRegex: control characters are what it refuses
+const SESSION_ID = /^[a-z0-9][a-z0-9-]{0,39}:[^\s\u0000-\u001f\u007f-\u009f\u061c\u200b-\u200f\u202a-\u202e\u2060-\u2069\ufeff]{1,190}$/
+const TOOL = /^[a-z0-9][a-z0-9-]{0,39}$/
+const MOVE_ID = /^[A-Za-z0-9_-]{8,64}$/
+
+export interface Move {
+  id: string
+  session: string
+  title: string | null
+  from: string
+  to: string
+  way: Way | null
+  state: string
+}
+
+export interface MoveResult {
+  way?: string
+  open?: string
+  newSession?: string | null
+  notes?: string[]
+  error?: string
+  at: string
+}
+
+/** Whether the person said yes, no, did not answer in time, or cannot be asked here. */
+export type Answer = "yes" | "no" | "timeout" | "unavailable"
+export type Ask = (question: string) => Answer
+
+/**
+ * Text for the person (a dialog, `brain moves`): one line, without control, bidirectional or zero-width characters, so
+ * text from a session or the website cannot rewrite the line, hide words or reorder them.
+ */
+// biome-ignore lint/suspicious/noControlCharactersInRegex: control characters are what it removes
+export const plainText = (s: string, max = 80) => s.replace(/[\u0000-\u001f\u007f-\u009f؜​-‏‪-‮⁠-⁩]/g, " ").replace(/\s+/g, " ").trim().slice(0, max)
+
+// ---- what waits here ------------------------------------------------------------------------------------------------------
+
+/** Moves waiting for the person here (no way to ask when they came), and results the account has not taken yet. */
+export const pendingPath = (home: string) => join(brainDir(home), "moves.json")
+type PendingMove = Move & { askedAt: string }
+interface Unsent {
+  id: string
+  state: "done" | "refused" | "failed"
+  result: MoveResult
+  at: string
+}
+interface Local {
+  moves: PendingMove[]
+  unsent: Unsent[]
+}
+/** The account lets a move wait an hour (a claimed one longer); one waiting here longer than a day is dropped. */
+export const PENDING_FOR_MS = 60 * 60_000
+const UNSENT_FOR_MS = 24 * 60 * 60_000
+
+function readLocal(home: string, now = Date.now()): Local {
+  try {
+    const j = JSON.parse(readFileSync(pendingPath(home), "utf8"))
+    const moves = (Array.isArray(j?.moves) ? j.moves : []).filter((m: any) => m && typeof m.id === "string" && typeof m.session === "string" && typeof m.to === "string" && now - Date.parse(m.askedAt) < PENDING_FOR_MS)
+    const unsent = (Array.isArray(j?.unsent) ? j.unsent : []).filter((u: any) => u && typeof u.id === "string" && typeof u.state === "string" && now - Date.parse(u.at) < UNSENT_FOR_MS)
+    return { moves, unsent }
+  } catch {
+    return { moves: [], unsent: [] }
+  }
+}
+/** The file changed under the brain lock: read again, changed, written (a round and `brain moves approve` never lose each other's change). */
+function changeLocal<T>(home: string, change: (l: Local) => T): T {
+  return withBrainLockSync(
+    home,
+    () => {
+      const l = readLocal(home)
+      const r = change(l)
+      writePrivateJson(pendingPath(home), l)
+      return r
+    },
+    { what: "moves from the dashboard" },
+  )
+}
+export const readPending = (home: string, now = Date.now()) => ({ moves: readLocal(home, now).moves })
+
+// ---- what the account sends -------------------------------------------------------------------------------------------------
+
+/** A move as the account sends it, if it is one brain can act on; anything else is left alone. */
+export function moveFrom(raw: unknown): Move | undefined {
+  const m = raw && typeof raw === "object" ? (raw as Record<string, unknown>) : {}
+  if (typeof m.id !== "string" || !MOVE_ID.test(m.id)) return undefined
+  if (typeof m.session !== "string" || !SESSION_ID.test(m.session)) return undefined
+  if (typeof m.to !== "string" || !TOOL.test(m.to)) return undefined
+  const way = WAYS.includes(m.way as Way) ? (m.way as Way) : null
+  const title = typeof m.title === "string" ? plainText(m.title, 120) || null : null
+  return { id: m.id, session: m.session, title, from: m.session.slice(0, m.session.indexOf(":")), to: m.to, way, state: typeof m.state === "string" ? m.state : "waiting" }
+}
+
+/** The session by its exact `<tool>:<id>`, as `brain session list` prints it: never a shortened id, never another one. */
+export async function exactSession(home: string, id: string): Promise<{ ref: SessionRef } | { why: string }> {
+  const i = id.indexOf(":")
+  if (i <= 0) return { why: "not a session id" }
+  const tool = id.slice(0, i)
+  const sid = id.slice(i + 1)
+  const { desktopHolds, listSessions, loadAdapters } = await import("./session/ops.ts")
+  const { readerFor } = await loadAdapters()
+  if (!readerFor(tool)) return { why: `brain does not read ${tool} sessions on this computer` }
+  const { refs } = await listSessions(home, tool)
+  const ref = refs.find((r) => r.sourceId === sid)
+  if (ref) return { ref }
+  // An id from a list uploaded before the desktop apps were told apart: the same session, now listed as the app's. Exact
+  // ids only, as above.
+  if (tool === "claude-code") {
+    const desk = (await listSessions(home, "claude-desktop")).refs.find((r) => desktopHolds(r, sid))
+    if (desk) return { ref: desk }
+  }
+  if (tool === "codex") {
+    const desk = (await listSessions(home, "codex-desktop")).refs.find((r) => r.sourceId === sid)
+    if (desk) return { ref: desk }
+  }
+  return { why: "this session is not on this computer any more" }
+}
+
+// ---- asking the person ------------------------------------------------------------------------------------------------------
+
+/** The dialog that asks: macOS (osascript), Linux with a desktop (zenity, kdialog); 2 minutes, then no answer. "Don't move" is the default. */
+export function askOnDesktop(question: string, env: Record<string, string | undefined> = process.env): Answer {
+  try {
+    if (process.platform === "darwin") {
+      // The question goes in as an argument, never into the script's text.
+      const p = Bun.spawnSync(
+        [
+          "osascript",
+          "-e",
+          "on run argv",
+          "-e",
+          'display dialog (item 1 of argv) buttons {"Don’t move", "Move"} default button "Don’t move" cancel button "Don’t move" with title "brain" giving up after 120',
+          "-e",
+          "end run",
+          question,
+        ],
+        { stdout: "pipe", stderr: "pipe", timeout: 130_000 },
+      )
+      const out = p.stdout.toString()
+      if (/gave up:true/.test(out)) return "timeout"
+      if (/button returned:Move\b/.test(out)) return "yes"
+      // "Don't move" (the cancel button) exits 1 with "User canceled" (-128); anything else means no dialog could be shown.
+      return /-128|canceled/i.test(p.stderr.toString()) ? "no" : "unavailable"
+    }
+    if (process.platform === "linux" && (env.DISPLAY || env.WAYLAND_DISPLAY)) {
+      if (Bun.which("zenity")) {
+        const p = Bun.spawnSync(["zenity", "--question", "--no-markup", "--default-cancel", "--title=brain", `--text=${question}`, "--ok-label=Move", "--cancel-label=Don't move", "--timeout=120"], { stdout: "ignore", stderr: "ignore", timeout: 130_000 })
+        return p.exitCode === 0 ? "yes" : p.exitCode === 5 ? "timeout" : p.exitCode === 1 ? "no" : "unavailable"
+      }
+      if (Bun.which("kdialog")) {
+        const safe = question.replaceAll("&", "&amp;").replaceAll("<", "&lt;")
+        const p = Bun.spawnSync(["kdialog", "--title", "brain", "--yes-label", "Move", "--no-label", "Don't move", "--yesno", safe], { stdout: "ignore", stderr: "ignore", timeout: 130_000 })
+        return p.exitCode === 0 ? "yes" : p.exitCode === 1 ? "no" : "unavailable"
+      }
+    }
+  } catch {}
+  return "unavailable"
+}
+
+/** What the person is asked: the session brain found (its own title, folder and tool), never the website's words. */
+async function questionFor(ref: SessionRef, to: string): Promise<string> {
+  const { loadAdapters } = await import("./session/ops.ts")
+  const { readerFor } = await loadAdapters()
+  const label = (t: string) => plainText(readerFor(t === "cursor" ? "cursor-ide" : t)?.label ?? t, 40)
+  const title = plainText(ref.title ?? "", 80) || "an untitled session"
+  const folder = ref.cwd ? plainText(basename(ref.cwd), 40) : ""
+  return `Move "${title}"${folder ? ` (folder ${folder})` : ""} from ${label(ref.tool)} to ${label(to)}? Asked from your 100xprompt dashboard.`
+}
+
+// ---- talking to the account -----------------------------------------------------------------------------------------------
+
+type Call = (method: string, path: string, body?: unknown) => Promise<{ status: number; json: any }>
+
+function caller(home: string, o: { fetchImpl?: typeof fetch; timeoutMs?: number }): Call | undefined {
+  const token = readMachineToken(home)
+  const base = gatewayUrl(home)
+  if (!token || !safeUrl(`${base}${MOVES_PATH}`)) return undefined
+  return async (method, path, body) => {
+    const res = await (o.fetchImpl ?? fetch)(`${base}${path}`, {
+      method,
+      headers: { Authorization: `Bearer ${token}`, ...(body ? { "Content-Type": "application/json" } : {}) },
+      ...(body ? { body: JSON.stringify(body) } : {}),
+      redirect: "manual",
+      signal: AbortSignal.timeout(o.timeoutMs ?? 10_000),
+    })
+    const text = await res.text().catch(() => "")
+    let json: any
+    try {
+      json = text ? JSON.parse(text) : undefined
+    } catch {}
+    return { status: res.status, json }
+  }
+}
+
+/** A change of the move's state: "ok", "gone" (cancelled, expired, or not this computer's: never retried), or "later". */
+async function postState(call: Call, id: string, state: string, result?: MoveResult): Promise<"ok" | "gone" | "later"> {
+  try {
+    const r = await call("POST", `${MOVES_PATH}/${encodeURIComponent(id)}`, { state, ...(result ? { result } : {}) })
+    if (r.status === 200) return "ok"
+    return r.status === 409 || r.status === 404 || r.status === 403 ? "gone" : "later"
+  } catch {
+    return "later"
+  }
+}
+
+/** A result the account did not take for now is kept and sent again next round. */
+async function sendResult(home: string, call: Call | undefined, id: string, state: Unsent["state"], result: MoveResult): Promise<void> {
+  const sent = call ? await postState(call, id, state, result) : "later"
+  if (sent === "later")
+    try {
+      changeLocal(home, (l) => {
+        l.unsent = [...l.unsent.filter((u) => u.id !== id), { id, state, result, at: new Date().toISOString() }]
+      })
+    } catch {}
+}
+
+async function resendUnsent(home: string, call: Call): Promise<void> {
+  for (const u of readLocal(home).unsent) {
+    const sent = await postState(call, u.id, u.state, u.result)
+    if (sent !== "later")
+      try {
+        changeLocal(home, (l) => {
+          l.unsent = l.unsent.filter((x) => x.id !== u.id)
+        })
+      } catch {}
+  }
+}
+
+// ---- moving ---------------------------------------------------------------------------------------------------------------
+
+const cleanNote = (s: string, home: string) => plainText(cleanText(s, home), 300)
+
+/**
+ * The command that opens the moved session, as the account may see it: no link (a brief's link carries the brief's text),
+ * and the home folder, plain or URL-encoded, written ~.
+ */
+export function openForAccount(open: string, home: string): string {
+  const parts = open.split(/\s*&&\s*/).filter((p) => !/[a-z][a-z0-9+.-]*:\/\//i.test(p) && !/%2F/i.test(p))
+  let t = parts.join(" && ")
+  if (home) {
+    // ~ is expanded only outside quotes: '<home>/My Projects' becomes ~/'My Projects', never '~/My Projects'.
+    t = t.replaceAll(`'${home}/`, "~/'").replaceAll(`'${home}'`, "~").replaceAll(`"${home}/`, '~/"').replaceAll(`"${home}"`, "~")
+    for (const h of [home, encodeURIComponent(home)]) t = t.replaceAll(h, "~")
+  }
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: control characters are what it removes
+  return cleanText(t, home).replace(/[\u0000-\u001f\u007f-\u009f]/g, " ").slice(0, 500)
+}
+
+/** Runs one move here, for the session found by its exact id. */
+export async function runMove(home: string, m: Move, ref: SessionRef): Promise<{ state: "done" | "failed"; result: MoveResult }> {
+  const at = () => new Date().toISOString()
+  const { loadAdapters, moveSession, readSession } = await import("./session/ops.ts")
+  const { writersFor, readerFor } = await loadAdapters()
+  if (!writersFor(m.to).length) return { state: "failed", result: { error: `brain can't continue sessions in "${m.to}" on this computer`, at: at() } }
+  if (ref.tool === m.to) return { state: "failed", result: { error: "the session is already in that tool", at: at() } }
+  try {
+    const s = await readSession(home, ref)
+    // A move from afar goes to the session's own folder; brain's own folder (the service runs in /) is never a guess for it.
+    const cwd = s.header.project.cwd ?? ref.cwd
+    if (!cwd) return { state: "failed", result: { error: `${plainText(readerFor(ref.tool)?.label ?? ref.tool, 40)} did not record this session's folder: move it from a terminal in that folder (brain session continue ${ref.tool}:${ref.sourceId} --in ${m.to})`, at: at() } }
+    const r = await moveSession(home, s, m.to, { dryRun: false, cwd, ...(m.way ? { way: m.way } : {}) })
+    if (!r.ok) return { state: "failed", result: { error: cleanNote(r.why, home), notes: r.notes.slice(0, 5).map((n) => cleanNote(n, home)), at: at() } }
+    const w = r.result
+    const toReader = w.tool === "cursor" ? "cursor-ide" : readerFor(w.tool) ? w.tool : m.to
+    const notes = [...r.notes, ...(w.note ? [`then: ${w.note}`] : []), ...(w.lost.length ? [`not carried over: ${w.lost.join("; ")}`] : [])]
+    return {
+      state: "done",
+      result: { way: w.way, open: openForAccount(w.open, home), newSession: w.sessionId ? `${toReader}:${w.sessionId}`.slice(0, 200) : null, notes: notes.slice(0, 5).map((n) => cleanNote(n, home)), at: at() },
+    }
+  } catch (e) {
+    return { state: "failed", result: { error: cleanNote(`the move stopped: ${String((e as Error)?.message ?? e)}`, home), at: at() } }
+  }
+}
+
+export interface MovesRound {
+  done: number
+  refused: number
+  failed: number
+  /** Left waiting here for `brain moves approve`. */
+  pending: number
+  /** Why the moves could not be fetched, when they could not. */
+  why?: string
+}
+
+/** One round: the account's waiting moves, as `moves.fromDashboard` says. At most `max` moves a round. */
+export async function processMoves(home: string, o: { fetchImpl?: typeof fetch; ask?: Ask; say?: (l: string) => void; max?: number; setting?: MovesSetting } = {}): Promise<MovesRound> {
+  const out: MovesRound = { done: 0, refused: 0, failed: 0, pending: 0 }
+  const call = caller(home, o)
+  if (!call) return { ...out, why: "not paired" }
+  await resendUnsent(home, call)
+  let list: Move[]
+  try {
+    const r = await call("GET", `${MOVES_PATH}?machine=${encodeURIComponent(machineId(home))}`)
+    if (r.status !== 200 || !Array.isArray(r.json?.moves)) return { ...out, why: `the gateway answered HTTP ${r.status}` }
+    list = r.json.moves.map(moveFrom).filter((m: Move | undefined): m is Move => !!m)
+  } catch (e) {
+    return { ...out, why: (e as Error)?.name === "TimeoutError" ? "the gateway did not answer in time" : `could not reach ${gatewayUrl(home)}` }
+  }
+  const say = o.say ?? (() => {})
+  const waitingHere = new Set(readLocal(home).moves.map((p) => p.id))
+  for (const m of list.filter((x) => x.state === "waiting" && !waitingHere.has(x.id)).slice(0, o.max ?? 3)) {
+    const setting = o.setting ?? movesSetting(home)
+    if (setting === "off") {
+      await sendResult(home, call, m.id, "refused", { error: "moves from the dashboard are off on this computer (brain settings set moves.fromDashboard ask)", at: new Date().toISOString() })
+      out.refused++
+      say(`refused a move from the dashboard (moves are off here): ${m.session} to ${m.to}`)
+      continue
+    }
+    // Claimed before anything happens: a cancelled or expired move is dropped, and no other round takes this one again.
+    if ((await postState(call, m.id, "asking")) !== "ok") continue
+    const found = await exactSession(home, m.session)
+    if ("why" in found) {
+      await sendResult(home, call, m.id, "failed", { error: found.why, at: new Date().toISOString() })
+      out.failed++
+      continue
+    }
+    if (setting === "ask") {
+      const answer = (o.ask ?? askOnDesktop)(await questionFor(found.ref, m.to))
+      if (answer === "unavailable") {
+        try {
+          changeLocal(home, (l) => {
+            l.moves = [...l.moves.filter((p) => p.id !== m.id), { ...m, title: plainText(found.ref.title ?? "", 120) || null, askedAt: new Date().toISOString() }]
+          })
+        } catch {}
+        out.pending++
+        say(`a move from the dashboard waits for you here: brain moves approve ${m.id}`)
+        continue
+      }
+      if (answer !== "yes") {
+        await sendResult(home, call, m.id, "refused", { error: answer === "timeout" ? "no answer on this computer within 2 minutes" : "refused on this computer", at: new Date().toISOString() })
+        out.refused++
+        continue
+      }
+    }
+    const r = await runMove(home, m, found.ref)
+    await sendResult(home, call, m.id, r.state, r.result)
+    if (r.state === "done") out.done++
+    else out.failed++
+    say(`${r.state === "done" ? "moved" : "could not move"} ${m.session} to ${m.to}${r.result.error ? `: ${r.result.error}` : ""}`)
+  }
+  return out
+}
+
+/** `brain moves approve|refuse <id>`: a move waiting here (its full id, or a start of at least 4 characters that is unique). */
+export async function decidePending(home: string, id: string, approve: boolean, o: { fetchImpl?: typeof fetch } = {}): Promise<{ ok: boolean; message: string }> {
+  // Taken out of the list under the lock before anything runs: two approvals never run one move twice.
+  let picked: PendingMove | string
+  try {
+    picked = changeLocal(home, (l): PendingMove | string => {
+      const want = id.trim()
+      const exact = l.moves.find((p) => p.id === want)
+      const matches = exact ? [exact] : want.length >= 4 ? l.moves.filter((p) => p.id.startsWith(want)) : []
+      if (!matches.length) return want.length < 4 && !exact ? "give the move's id (brain moves lists them)" : `no move "${want}" waits here (brain moves lists them)`
+      if (matches.length > 1) return `"${want}" matches ${matches.length} moves: give the whole id (brain moves lists them)`
+      l.moves = l.moves.filter((p) => p.id !== matches[0]!.id)
+      return matches[0]!
+    })
+  } catch (e) {
+    return { ok: false, message: `could not read the moves waiting here: ${String((e as Error)?.message ?? e).slice(0, 200)}` }
+  }
+  if (typeof picked === "string") return { ok: false, message: picked }
+  const m = picked
+  const call = caller(home, o)
+  if (!approve) {
+    await sendResult(home, call, m.id, "refused", { error: "refused on this computer", at: new Date().toISOString() })
+    return { ok: true, message: `refused the move of ${m.session} to ${m.to}` }
+  }
+  const found = await exactSession(home, m.session)
+  if ("why" in found) {
+    await sendResult(home, call, m.id, "failed", { error: found.why, at: new Date().toISOString() })
+    return { ok: false, message: `could not move ${m.session}: ${found.why}` }
+  }
+  const r = await runMove(home, m, found.ref)
+  await sendResult(home, call, m.id, r.state, r.result)
+  if (r.state !== "done") return { ok: false, message: `could not move ${m.session} to ${m.to}: ${r.result.error}` }
+  return { ok: true, message: `moved ${m.session} to ${m.to}${r.result.open ? `\nNext: ${r.result.open}` : ""}` }
+}
+
+/** What `brain moves`, `brain status` and the report say about them. */
+export function movesState(home: string): { setting: MovesSetting; waiting: number } {
+  return { setting: movesSetting(home), waiting: readLocal(home).moves.length }
+}

package/src/service.ts

@@ -324,6 +324,8 @@ export function refreshEnv(home: string, env: Env = process.env) {
 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
@@ -415,8 +417,23 @@ export async function runService(home: string, o: LoopOptions = {}): Promise<"st
       }
       // Written before the report: the report says this loop runs.
       keepTurn(home, state, loopEvery(env))
-      if (x.ok && (x.received.length || x.applied.length)) {
-        say(`took ${x.received.length} change(s) from your account, applied ${x.applied.length}`)
+      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 {

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>)` }
+}

package/src/session/ops.ts

@@ -0,0 +1,111 @@
+// Listing, finding, reading and moving sessions, for `brain session ...` and for brain's background service (a move asked
+// from the dashboard, docs/sessions-contract.md). Nothing here prints or exits: callers say what happened.
+import { resolve } from "node:path"
+import type { SessionRef, Way, WriteResult } from "../adapters/types.ts"
+import { toolLabel } from "../brief.ts"
+import { prepare, sessionTokens } from "../memory/prepare.ts"
+import type { Session } from "./types.ts"
+
+// Adapters load only for what uses them: every tool's session-start hook runs cli.ts, and one adapter failing to load
+// (or loading slowly) must not hold up or break a session in another tool.
+let loaded: typeof import("../adapters/index.ts") | undefined
+export const loadAdapters = async () => (loaded ??= await import("../adapters/index.ts"))
+
+/** Every session brain can read under `home` (one tool's with `tool`), newest first, and the tools it could not list. */
+export async function listSessions(home: string, tool?: string): Promise<{ refs: SessionRef[]; errors: string[] }> {
+  const { READERS } = await loadAdapters()
+  const readers = tool ? READERS.filter((r) => r.tool === tool) : READERS
+  const errors: string[] = []
+  const lists = await Promise.all(
+    readers.map(async (r) => {
+      try {
+        return await r.list(home)
+      } catch (e) {
+        errors.push(`${r.tool}: ${(e as Error).message}`)
+        return []
+      }
+    }),
+  )
+  return { refs: lists.flat().sort((a, b) => (b.updatedAt ?? "").localeCompare(a.updatedAt ?? "")), errors }
+}
+
+/** Whether a Claude Desktop session's transcripts (the current one or an earlier one) include Claude Code transcript `id`. */
+export const desktopHolds = (r: SessionRef, id: string) =>
+  r.extra?.cliSessionId === id || (Array.isArray(r.extra?.priorCliSessionIds) && (r.extra.priorCliSessionIds as unknown[]).includes(id))
+
+/** A session by `<tool>:<id>` (as `brain session list` prints it) or a unique start of its id. */
+export async function findSession(home: string, given: string): Promise<{ ref: SessionRef } | { error: string }> {
+  // An id copied from an older, shortened list ends in "…": what comes before it is still a unique start.
+  const id = given.replace(/…$/, "")
+  const { readerFor } = await loadAdapters()
+  const colon = id.indexOf(":")
+  const tool = colon > 0 && readerFor(id.slice(0, colon)) ? id.slice(0, colon) : undefined
+  const want = tool ? id.slice(colon + 1) : id
+  if (!want) return { error: `no session "${id}"; see \`brain session list\`` }
+  const { refs } = await listSessions(home, tool)
+  const exact = refs.filter((r) => r.sourceId === want)
+  const matches = exact.length ? exact : refs.filter((r) => r.sourceId.startsWith(want))
+  if (!matches.length && (!tool || tool === "claude-code")) {
+    // A Claude Code transcript Claude Desktop keeps a record of (its current one or an earlier one) is listed as its Claude
+    // Desktop session (an id from before).
+    const desk = (await listSessions(home, "claude-desktop")).refs.find((r) => desktopHolds(r, want))
+    if (desk) return { ref: desk }
+  }
+  if (!matches.length && (!tool || tool === "codex")) {
+    // A Codex thread the Codex app started is listed as Codex Desktop's (an id from before).
+    const desk = (await listSessions(home, "codex-desktop")).refs.find((r) => r.sourceId === want)
+    if (desk) return { ref: desk }
+  }
+  if (!matches.length) return { error: `no session "${id}"; see \`brain session list\`` }
+  if (matches.length > 1) return { error: `"${id}" matches ${matches.length} sessions (${matches.slice(0, 4).map((r) => `${r.tool}:${r.sourceId}`).join(", ")}…); give more of the id` }
+  return { ref: matches[0]! }
+}
+
+export async function readSession(home: string, ref: SessionRef): Promise<Session> {
+  const { readerFor } = await loadAdapters()
+  return readerFor(ref.tool)!.read(ref, home)
+}
+
+export interface MoveOptions {
+  way?: Way
+  cwd?: string
+  dryRun: boolean
+  lean?: boolean
+  noMemory?: boolean
+  budget?: number
+  tidy?: false
+}
+
+export type MoveOutcome =
+  | { ok: true; result: WriteResult; notes: string[]; skipped: string[] }
+  | { ok: false; why: string; notes: string[]; skipped: string[] }
+
+/**
+ * `source` continued in `target`: the first of its ways that is ready (or `way`), the session prepared as `brain session
+ * continue` prepares it (lean, memory, budget), written, and the move logged for the dashboard. Opens nothing.
+ */
+export async function moveSession(home: string, source: Session, target: string, opts: MoveOptions): Promise<MoveOutcome> {
+  const { writersFor, readerFor } = await loadAdapters()
+  const candidates = writersFor(target).filter((w) => !opts.way || w.way === opts.way)
+  if (!candidates.length) return { ok: false, why: `can't continue in "${target}"${opts.way ? ` by ${opts.way}` : ""}; see \`brain session targets\``, notes: [], skipped: [] }
+  const cwd = resolve(opts.cwd ?? source.header.project.cwd ?? process.cwd())
+  const prepared = await prepare(source, { home, cwd, dryRun: opts.dryRun, ...(opts.lean !== undefined ? { lean: opts.lean } : {}), ...(opts.noMemory ? { noMemory: true } : {}), ...(opts.budget ? { budget: opts.budget } : {}), ...(opts.tidy === false ? { tidy: false } : {}) })
+  const wopts = { home, cwd, dryRun: opts.dryRun, brief: prepared.brief }
+  const skipped: string[] = []
+  for (const w of candidates) {
+    const ready = await w.ready(wopts)
+    if (!ready.ok) {
+      skipped.push(`${w.way}: ${ready.why}`)
+      continue
+    }
+    const r = await w.write(prepared.session, wopts)
+    if (!r.dryRun) {
+      // The dashboard's conversion log: tools, way, title, project folder name and sizes; never the chat (src/dashboard/conversions.ts).
+      const { logConversion } = await import("../dashboard/conversions.ts")
+      const to = r.tool === "cursor" ? "cursor-ide" : r.tool
+      logConversion(home, { from: source.header.tool, fromLabel: readerFor(source.header.tool)?.label ?? toolLabel(source.header.tool), to: r.tool, toLabel: readerFor(to)?.label ?? w.label, way: r.way, title: source.header.title, cwd: source.header.project.cwd ?? cwd, turns: source.turns.length, tokens: sessionTokens(prepared.session), lean: prepared.lean })
+    }
+    return { ok: true, result: r, notes: prepared.notes, skipped }
+  }
+  return { ok: false, why: `no way to continue in "${target}" right now: ${skipped.join("; ")}`, notes: prepared.notes, skipped }
+}