@100xprompt/brain 0.1.3 → 0.1.5

package/src/settings/account.ts

@@ -0,0 +1,391 @@
+// Exchanging settings with the person's 100xprompt account (docs/settings-contract.md, section 5). A paired computer has
+// its own token (~/.brain/machine.key, from `brain pair`); model API keys never read or change settings.
+//
+//   1. send the outbox: what was changed here, one PATCH per level (this computer, all your computers). Accepted and
+//      refused changes leave it; refused ones are kept to be shown, and the account's value then applies again.
+//   2. fetch what the account has (GET, with the revision last seen: "unchanged" costs nothing).
+//   3. take it: the account's entries become this computer's and the person's levels, except settings only this computer
+//      can have and changes made here that are not sent yet. Changes from elsewhere go into the history.
+//   4. apply what that changed (apply.ts reconcile), and tell the account what applying gave.
+// Network calls never run under the brain lock; the whole exchange keeps to a time budget (3 s for commands). Never run
+// from the session hook, `brain mcp serve` or the background children. Anything the account answers is checked before it
+// is taken: an answer that cannot be read changes nothing here.
+import { existsSync, mkdirSync, rmSync } from "node:fs"
+import type { Env } from "../gateway/common.ts"
+import { writeAtomic } from "../fsutil.ts"
+import { withBrainLockSync } from "../lock.ts"
+import { gatewayUrl, safeUrl } from "../dashboard/send.ts"
+import { brainDir, MACHINE_TOKEN, machineId, machineKeyPath, readMachineToken } from "../dashboard/state.ts"
+import { readOrgConfig } from "../org/config.ts"
+import { type Row, reconcile } from "./apply.ts"
+import { checkValue, parseId, resolve } from "./catalog.ts"
+import { type Entry, type Level, readSettingsFile, same, type SettingsDoc, type Source, updateDoc, type Value } from "./store.ts"
+import { memoryOn } from "./values.ts"
+
+export { MACHINE_TOKEN, readMachineToken }
+
+export function storeMachineToken(home: string, token: string): void {
+  withBrainLockSync(home, () => {
+    mkdirSync(brainDir(home), { recursive: true, mode: 0o700 })
+    writeAtomic(machineKeyPath(home), `${token}\n`, 0o600)
+  })
+}
+
+export function forgetMachineToken(home: string): boolean {
+  const had = existsSync(machineKeyPath(home))
+  rmSync(machineKeyPath(home), { force: true })
+  return had
+}
+
+/**
+ * A computer the account knows afresh (paired again after "Remove this machine", or a copied ~/.brain paired as a computer
+ * of its own) has an empty document there: every value set at this computer's level here is sent again, and the next fetch
+ * starts from nothing, so the account's empty document never erases them. Not the dashboard's or an admin's: those are the
+ * account's to keep (a computer never sends them as its own; the gateway refuses that), and an account that forgot this
+ * computer forgot them too.
+ */
+export function sendAllAgain(home: string): void {
+  updateDoc(home, (d) => {
+    const at = new Date().toISOString()
+    for (const [id, e] of Object.entries(d.levels.computer)) {
+      const ref = parseId(id)
+      if ("error" in ref || ref.family.remote !== "yes" || !COMPUTER_SOURCES.includes(e.source)) continue
+      d.outbox = d.outbox.filter((c) => !(c.id === id && c.level === "computer"))
+      d.outbox.push({ id, level: "computer", value: e.value, source: e.source, at: e.at || at, ...(e.command ? { command: e.command } : {}) })
+    }
+    delete d.sync.rev
+    d.sync.machine = machineId(home)
+  })
+}
+
+export interface Exchange {
+  paired: boolean
+  /** The account was reached (sending and fetching worked). */
+  ok: boolean
+  why?: string
+  /** Changes made here the account accepted. */
+  sent: number
+  refused: Array<{ id: string; code: string; message: string }>
+  /** Values that came from the account (changed since the last exchange). */
+  received: string[]
+  applied: Row[]
+  /** Values from the account this computer did not take, and why. */
+  held: Array<{ id: string; why: string }>
+}
+
+const LEVEL_OUT: Record<"computer" | "person", "machine" | "account"> = { computer: "machine", person: "account" }
+const SOURCES: Source[] = ["settings", "command", "dashboard", "admin", "local-page"]
+/** The sources a computer sends its changes with; the dashboard's and an admin's come only from the account. */
+const COMPUTER_SOURCES: Source[] = ["settings", "command", "local-page"]
+const isValue = (v: unknown): v is Value => typeof v === "boolean" || (typeof v === "number" && Number.isFinite(v)) || typeof v === "string"
+const obj = (v: unknown): Record<string, any> => (v && typeof v === "object" && !Array.isArray(v) ? (v as Record<string, any>) : {})
+const isObj = (v: unknown) => !!v && typeof v === "object" && !Array.isArray(v)
+const MEMORY_HELD = "this computer keeps memory on your team's server: only this computer turns it on (brain settings set memory.enabled on)"
+
+/** An entry as the account sends it, if it is one this brain can keep: a known setting the account may change, at a level it can be set at, with a valid value. */
+function entryFrom(id: string, level: Level, e: unknown): Entry | undefined {
+  const x = obj(e)
+  if (!isValue(x.value) || typeof x.at !== "string" || x.at.length > 40 || !Number.isFinite(Date.parse(x.at))) return undefined
+  const ref = parseId(id)
+  if ("error" in ref || ref.id !== id || ref.family.remote !== "yes" || !ref.family.levels.includes(level) || !checkValue(ref.family.type, x.value)) return undefined
+  return { value: x.value, source: SOURCES.includes(x.source) ? x.source : "dashboard", at: x.at, ...(Number.isSafeInteger(x.rev) ? { rev: x.rev } : {}) }
+}
+
+const sameEntry = (x: Entry | undefined, y: Entry | undefined) =>
+  x === y || (!!x && !!y && same(x.value, y.value) && x.source === y.source && x.at === y.at && x.rev === y.rev)
+
+/** "<machine>.<account>" as two numbers; undefined when it is not one. */
+const revParts = (r: unknown): [number, number] | undefined => {
+  const m = typeof r === "string" ? /^(\d{1,15})\.(\d{1,15})$/.exec(r) : null
+  return m ? [Number(m[1]), Number(m[2])] : undefined
+}
+
+/** Plain words for what the account answered. */
+function trouble(status: number, said: string): string {
+  if (status === 401) return "your account no longer takes this computer's token (was the computer removed in the dashboard?): pair it again with `brain pair`"
+  if (status === 403) return `your account refused this exchange${said ? ` (${said})` : ""}: pair this computer again with \`brain pair\``
+  if (status === 404) return "the gateway does not keep brain settings yet"
+  if (status === 429) return "too many exchanges for now; the next one carries everything"
+  return `the gateway answered HTTP ${status}${said ? `: ${said}` : ""}`
+}
+
+class Unreachable extends Error {}
+class Unreadable extends Error {}
+
+/**
+ * One exchange with the account. Does nothing (paired: false) on a computer that is not paired. Never throws; what went
+ * wrong is in `why` and kept in settings.json for `brain status`.
+ */
+export async function exchange(home: string, o: { env?: Env; fetchImpl?: typeof fetch; timeoutMs?: number; apply?: boolean } = {}): Promise<Exchange> {
+  const out: Exchange = { paired: false, ok: false, sent: 0, refused: [], received: [], applied: [], held: [] }
+  // The computer's id first: a ~/.brain copied from another computer gets its own id here, and drops that one's token.
+  const machine = machineId(home)
+  const token = readMachineToken(home)
+  if (!token) return { ...out, why: "this computer is not paired with your account (brain pair)" }
+  out.paired = true
+  const file = readSettingsFile(home)
+  if (file.problem) return { ...out, why: file.problem === "newer" ? "settings.json was written by a newer brain: update brain to exchange settings here" : "settings.json could not be read: `brain settings set` writes a new one" }
+  const base = gatewayUrl(home)
+  if (!safeUrl(`${base}/api/brain/settings`)) return { ...out, why: `the gateway address ${base} is not https; the token is never sent over it` }
+  const deadline = Date.now() + (o.timeoutMs ?? 3_000)
+  const call = async (method: string, path: string, body?: unknown): Promise<{ status: number; json: unknown }> => {
+    const left = deadline - Date.now()
+    if (left <= 0) throw Object.assign(new Error("out of time"), { name: "TimeoutError" })
+    let res: Response
+    try {
+      res = await (o.fetchImpl ?? fetch)(`${base}${path}`, {
+        method,
+        headers: { Authorization: `Bearer ${token}`, ...(body ? { "Content-Type": "application/json" } : {}) },
+        ...(body ? { body: JSON.stringify(body) } : {}),
+        // A redirect is not followed: it could carry the token to another host.
+        redirect: "manual",
+        signal: AbortSignal.timeout(Math.max(200, left)),
+      })
+    } catch (e) {
+      const n = (e as Error)?.name
+      if (n === "TimeoutError" || n === "AbortError") throw e
+      throw new Unreachable(String((e as Error)?.message ?? e))
+    }
+    // Reading the body may run out of time too: that is a failed exchange, never an empty answer.
+    const text = await res.text()
+    let json: unknown
+    try {
+      json = text ? JSON.parse(text) : undefined
+    } catch {
+      json = undefined
+    }
+    return { status: res.status, json }
+  }
+  const said = (j: any) => String(j?.error?.message ?? j?.error ?? j?.message ?? "").slice(0, 200)
+  const fail = (why: string): Exchange => {
+    try {
+      updateDoc(home, (d) => {
+        d.sync.lastError = why
+      })
+    } catch {}
+    return { ...out, why }
+  }
+
+  try {
+    // A computer the account knows afresh: everything set here goes again (see sendAllAgain).
+    if (file.doc.sync.machine !== machine) sendAllAgain(home)
+    // A change this computer cannot send as its own (an older brain queued the dashboard's) would wait for good and keep
+    // the account's value from being taken: it leaves the outbox.
+    if (readSettingsFile(home).doc.outbox.some((c) => !COMPUTER_SOURCES.includes(c.source)))
+      updateDoc(home, (d) => {
+        d.outbox = d.outbox.filter((c) => COMPUTER_SOURCES.includes(c.source))
+      })
+    // 1. Send what changed here.
+    const snapshot = readSettingsFile(home).doc.outbox
+    for (const level of ["computer", "person"] as const) {
+      const changes = snapshot.filter((c) => {
+        if (c.level !== level) return false
+        const r = parseId(c.id)
+        return !("error" in r) && r.family.remote === "yes"
+      })
+      if (!changes.length) continue
+      const r = await call("PATCH", "/api/brain/settings", { level: LEVEL_OUT[level], machine, changes: changes.map((c) => ({ id: c.id, value: c.value, source: c.source, at: c.at })) })
+      if (r.status !== 200) return fail(trouble(r.status, said(r.json)))
+      const j = obj(r.json)
+      if (!Array.isArray(j.accepted) || !Array.isArray(j.refused)) throw new Unreadable("PATCH")
+      const accepted = new Map<string, number>()
+      for (const a of j.accepted) if (typeof a?.id === "string") accepted.set(a.id, Number(a.rev))
+      const refused = j.refused.filter((x: any) => typeof x?.id === "string").map((x: any) => ({ id: String(x.id).slice(0, 80), code: String(x.code ?? "refused").slice(0, 40), message: String(x.message ?? "").slice(0, 200) }))
+      out.sent += accepted.size
+      out.refused.push(...refused)
+      const settledIds = new Set([...accepted.keys(), ...refused.map((x: { id: string }) => x.id)])
+      updateDoc(home, (d) => {
+        // Only what was sent leaves the outbox: a change made here meanwhile waits for the next exchange.
+        d.outbox = d.outbox.filter((c) => !(c.level === level && settledIds.has(c.id) && changes.some((s) => s.id === c.id && s.at === c.at && same(s.value, c.value))))
+        for (const [id, rev] of accepted) {
+          const e = d.levels[level][id]
+          if (e && Number.isSafeInteger(rev)) e.rev = rev
+        }
+        const at = new Date().toISOString()
+        for (const x of refused) {
+          const sent = changes.find((c) => c.id === x.id)
+          d.sync.refused.push({ id: x.id, level, value: sent?.value ?? null, code: x.code, message: x.message, at })
+        }
+        d.sync.refused = d.sync.refused.slice(-20)
+      })
+    }
+
+    // 2. Fetch what the account has. After a refusal the account's revision has not moved, but this computer must go back
+    // to the account's value: the whole state is fetched then.
+    const since = out.refused.length ? "" : (readSettingsFile(home).doc.sync.rev ?? "")
+    const r = await call("GET", `/api/brain/settings?machine=${encodeURIComponent(machine)}&since=${encodeURIComponent(since)}`)
+    if (r.status !== 200) return fail(trouble(r.status, said(r.json)))
+    const j = obj(r.json)
+    const now = new Date().toISOString()
+    if (j.unchanged === true && revParts(j.rev)) {
+      updateDoc(home, (d) => {
+        d.sync.lastSyncAt = now
+        delete d.sync.lastError
+      })
+    } else {
+      // Only an answer of the contract's shape is taken: anything else (an HTML page, `{}`) would erase every setting here.
+      const fetched = revParts(j.rev)
+      if (!fetched || !isObj(j.machine) || !isObj(j.machine.entries) || !isObj(j.account) || !isObj(j.account.entries)) throw new Unreadable("GET")
+      // 3. Take it.
+      const org = !!readOrgConfig(home)
+      updateDoc(home, (d) => {
+        // Another brain (a second terminal) may have taken a newer answer meanwhile: an older one is not taken over it.
+        const stored = revParts(d.sync.rev)
+        if (stored && (fetched[0] < stored[0] || fetched[1] < stored[1])) return
+        const pending = new Set(d.outbox.map((c) => `${c.level}\0${c.id}`))
+        // The levels as they were, to tell what taking the answer changes in the value in force here.
+        const before: SettingsDoc = { ...d, levels: { ...d.levels } }
+        // The same value written again on the account (a newer rev at another time: the dashboard's "try again").
+        const again: string[] = []
+        const next: Record<"computer" | "person", Record<string, Entry>> = { computer: {}, person: {} }
+        for (const [level, srv] of [
+          ["computer", j.machine.entries],
+          ["person", j.account.entries],
+        ] as Array<["computer" | "person", Record<string, unknown>]>) {
+          // Kept from here: settings only this computer can have, and changes not sent yet.
+          for (const [id, e] of Object.entries(d.levels[level])) {
+            const ref = parseId(id)
+            if (pending.has(`${level}\0${id}`) || "error" in ref || ref.family.remote !== "yes") next[level][id] = e
+          }
+          for (const [id, raw] of Object.entries(srv)) {
+            if (!Object.hasOwn(srv, id) || pending.has(`${level}\0${id}`) || Object.hasOwn(next[level], id)) continue
+            const e = entryFrom(id, level, raw)
+            if (!e) continue
+            const was = d.levels[level][id]
+            if (was && same(was.value, e.value) && was.source === e.source) {
+              if (e.rev !== undefined && was.rev !== undefined && e.rev > was.rev && e.at !== was.at) {
+                next[level][id] = { ...e, ...(was.command ? { command: was.command } : {}) }
+                again.push(id)
+              }
+              // The same value from the same source: kept as it is here (with the command that set it).
+              else next[level][id] = { ...was, ...(e.rev !== undefined ? { rev: e.rev } : {}) }
+            } else next[level][id] = e
+          }
+        }
+        // Memory turned on from afar on a computer that sends it to a team server: only this computer turns that on. Judged
+        // by the effect (whatever level or source did it): memory off before, on after.
+        const held: Array<{ id: string; why: string }> = []
+        if (org && !memoryOn(home, d) && memoryOn(home, { ...d, levels: { ...d.levels, computer: next.computer, person: next.person } })) {
+          for (const level of ["computer", "person"] as const) {
+            const was = d.levels[level]["memory.enabled"]
+            if (was) next[level]["memory.enabled"] = was
+            else delete next[level]["memory.enabled"]
+          }
+          held.push({ id: "memory.enabled", why: MEMORY_HELD })
+          d.applied["memory.enabled"] = { want: true, ok: false, at: now, error: MEMORY_HELD }
+        }
+        for (const level of ["computer", "person"] as const) {
+          for (const id of new Set([...Object.keys(d.levels[level]), ...Object.keys(next[level])])) {
+            const was = d.levels[level][id]
+            const now2 = next[level][id]
+            if (was && now2 && same(was.value, now2.value) && was.source === now2.source) continue
+            if (!was && !now2) continue
+            // A change from elsewhere goes into the history, with what it replaced here. A removal at this computer's
+            // level comes from the dashboard; one for all the person's computers may come from another computer.
+            d.history.push({
+              id,
+              level,
+              value: now2 ? now2.value : null,
+              source: now2?.source ?? (level === "computer" ? "dashboard" : "settings"),
+              at: now2?.at ?? now,
+              ...(was ? { replaced: { value: was.value, source: was.source, at: was.at, ...(was.command ? { command: was.command } : {}) } } : {}),
+            })
+            out.received.push(id)
+          }
+          d.levels[level] = next[level]
+        }
+        // Team defaults and locks come with step 4: until then the account sends none.
+        const locks: SettingsDoc["locks"] = {}
+        for (const [id, l] of Object.entries(obj(j.locks))) if (Object.hasOwn(obj(j.locks), id) && isValue(obj(l).value) && !("error" in parseId(id))) locks[id] = { value: obj(l).value }
+        d.locks = locks
+        // The value in force here set from the account (set, set again, the same value from another source, or cleared down
+        // to another level's equal value) is applied afresh, even where it failed or was changed by hand since: that is the
+        // person setting it (again). A change at a level that does not decide here applies nothing.
+        // A setting with nothing to apply set again is still taken, so what it gave is said (below, after applying).
+        for (const id of new Set([...out.received, ...again])) {
+          const ref = parseId(id)
+          if ("error" in ref) continue
+          const a = resolve(d, ref)
+          if (a.value === undefined || (a.from !== "computer" && a.from !== "person" && a.from !== "team")) continue
+          const b = resolve(before, ref)
+          if (b.from === a.from && sameEntry(b.entry, a.entry)) continue
+          if (ref.family.apply) delete d.applied[id]
+          if (!out.received.includes(id)) out.received.push(id)
+        }
+        d.history = d.history.slice(-200)
+        d.sync.rev = `${fetched[0]}.${fetched[1]}`
+        d.sync.lastSyncAt = now
+        d.sync.machine = machine
+        delete d.sync.lastError
+        d.sync.held = held
+        out.held = held
+      })
+    }
+    out.ok = true
+  } catch (e) {
+    const name = (e as Error)?.name
+    if (name === "TimeoutError" || name === "AbortError") return fail("the account did not answer in time; changes made here wait for the next exchange")
+    if (e instanceof Unreachable) return fail(`could not reach ${base}`)
+    if (e instanceof Unreadable) return fail("the account's answer could not be read; nothing here was changed")
+    return fail(`the exchange stopped: ${String((e as Error)?.message ?? e).slice(0, 200)}`)
+  }
+
+  // 4. Apply what changed, and say what it gave (a value held back here counts as failed).
+  if (o.apply !== false) {
+    let elsewhere: string[] = []
+    try {
+      const r = await reconcile(home, { env: o.env ?? process.env })
+      out.applied = r.applied
+      elsewhere = r.elsewhere
+    } catch {}
+    const applied: Record<string, unknown> = {}
+    const at = new Date().toISOString()
+    for (const row of out.applied)
+      applied[row.id] = { want: row.value ?? null, ok: row.state !== "failed" && row.state !== "not on this computer" && row.state !== "can't read", ...(row.error ? { error: row.error } : {}), ...(row.notes.length ? { notes: row.notes.slice(0, 5) } : {}), at }
+    // A value taken that has nothing to apply (brain reads it where it is used: lean.*, memory.enabled) is in force once
+    // taken; one for a tool not on this computer waits for that tool. Both are said, so the dashboard never waits on them.
+    // (A value in force set from the account is applied afresh above, so it is among the applied rows.)
+    if (out.received.length) {
+      const doc = readSettingsFile(home).doc
+      for (const id of out.received) {
+        const ref = parseId(id)
+        if ("error" in ref || Object.hasOwn(applied, id) || out.held.some((h) => h.id === id)) continue
+        const want = resolve(doc, ref).value
+        if (want === undefined) continue
+        if (!ref.family.apply) applied[id] = { want, ok: true, at }
+        else if (elsewhere.includes(id)) applied[id] = { want, ok: false, error: `${ref.tool ?? "this tool"} is not on this computer: brain applies it once it is`, at }
+      }
+    }
+    for (const h of out.held) applied[h.id] = { want: true, ok: false, error: h.why, at }
+    if (Object.keys(applied).length && Date.now() < deadline) {
+      try {
+        await call("POST", "/api/brain/settings/applied", { machine, applied })
+      } catch {}
+    }
+  }
+  return out
+}
+
+/** What `brain status` says about the account exchange. */
+export function exchangeState(home: string): {
+  paired: boolean
+  lastSyncAt?: string
+  lastError?: string
+  waiting: number
+  refused: SettingsDoc["sync"]["refused"]
+  held: Array<{ id: string; why: string }>
+} {
+  const d = readSettingsFile(home).doc
+  const waiting = d.outbox.filter((c) => {
+    const r = parseId(c.id)
+    return !("error" in r) && r.family.remote === "yes"
+  }).length
+  return {
+    paired: !!readMachineToken(home),
+    ...(d.sync.lastSyncAt ? { lastSyncAt: d.sync.lastSyncAt } : {}),
+    ...(d.sync.lastError ? { lastError: d.sync.lastError } : {}),
+    waiting,
+    refused: d.sync.refused,
+    held: d.sync.held,
+  }
+}