@100xprompt/brain 0.1.3 → 0.1.4

package/src/settings/store.ts

@@ -0,0 +1,216 @@
+// brain's settings: <home>/.brain/settings.json (0600 in a 0700 folder). What each setting should be, at each level, and
+// what happened when brain applied it. One file for every way of changing brain (`brain settings`, brain's other commands,
+// later the dashboard and the local page), so each of them sees what the others did. This file only keeps the record:
+// catalog.ts says which settings exist and how each is read and applied, apply.ts changes things.
+//
+//   levels    computer (this computer), person (all of the person's computers), team (the team's default). The first that
+//             has a value applies, unless the team admin locked the setting: then the lock does.
+//   outbox    changes made here that the person's 100xprompt account has not received yet (one per setting and level).
+//   history   the last 200 changes, with who made them and what each replaced.
+//   applied   for each setting: the value brain last applied, and whether that worked (or why not).
+//
+// Written only under the brain lock (lock.ts), atomically; read without it.
+import { existsSync, mkdirSync, readFileSync, renameSync } from "node:fs"
+import { join } from "node:path"
+import { writeAtomic } from "../fsutil.ts"
+import { withBrainLockSync } from "../lock.ts"
+
+export const SETTINGS_SCHEMA = 1
+export const settingsFile = (home: string) => join(home, ".brain", "settings.json")
+export const HISTORY_MAX = 200
+
+export type Value = boolean | number | string
+export type Level = "computer" | "person" | "team"
+/** Highest first: the first level with a value applies. */
+export const LEVELS: Level[] = ["computer", "person", "team"]
+/** Who made a change: `brain settings`, another brain command (gateway connect, mcp install, ...), the dashboard, the team admin, the local page. */
+export type Source = "settings" | "command" | "dashboard" | "admin" | "local-page"
+
+export interface Entry {
+  value: Value
+  source: Source
+  /** When it was made, by the clock where it was made: shown, never used to order changes. */
+  at: string
+  /** The command that made it, for source "command" (`brain gateway connect`). */
+  command?: string
+  /** The order the person's account gave it (from the dashboard sync, later). */
+  rev?: number
+}
+
+export interface Change {
+  id: string
+  level: Level
+  /** null: the setting was cleared at this level. */
+  value: Value | null
+  source: Source
+  at: string
+  command?: string
+  /** The value it replaced at this level, when another way of changing brain had set it. */
+  replaced?: { value: Value; source: Source; at: string; command?: string }
+}
+
+export interface Applied {
+  /** The value brain applied (or tried to). */
+  want: Value
+  ok: boolean
+  at: string
+  error?: string
+  /** What the person should know (an exported key that wins over the tool's config, say). */
+  notes?: string[]
+  /** The tool is not on this computer. */
+  missing?: boolean
+}
+
+/** The exchange with the person's account (account.ts). */
+export interface SyncState {
+  /** The account's revision last fetched ("<machine rev>.<account rev>"). */
+  rev?: string
+  lastSyncAt?: string
+  /** Why the last exchange did not get through, cleared by one that does. */
+  lastError?: string
+  /** Changes made here that the account refused for good (kept to be shown), newest last, at most 20. */
+  refused: Array<{ id: string; level: Level; value: Value | null; code: string; message: string; at: string }>
+  /** Values from the account this computer did not take, and why. */
+  held: Array<{ id: string; why: string }>
+  /** The computer id the last exchange was for (a new one: the account knows this computer afresh). */
+  machine?: string
+}
+
+export interface SettingsDoc {
+  schema: number
+  levels: Record<Level, Record<string, Entry>>
+  locks: Record<string, { value: Value; at?: string; by?: string }>
+  outbox: Change[]
+  history: Change[]
+  applied: Record<string, Applied>
+  sync: SyncState
+}
+
+export const emptyDoc = (): SettingsDoc => ({ schema: SETTINGS_SCHEMA, levels: { computer: {}, person: {}, team: {} }, locks: {}, outbox: [], history: [], applied: {}, sync: { refused: [], held: [] } })
+
+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 list = (v: unknown): any[] => (Array.isArray(v) ? v : [])
+const isChange = (c: any) => c && typeof c.id === "string" && LEVELS.includes(c.level) && (c.value === null || isValue(c.value)) && typeof c.at === "string"
+
+/** Whatever the file holds, made into a document of the known shape (anything malformed is dropped, not trusted). */
+function normalize(raw: Record<string, any>): SettingsDoc {
+  const d = emptyDoc()
+  d.schema = typeof raw.schema === "number" ? raw.schema : SETTINGS_SCHEMA
+  const levels = obj(raw.levels)
+  for (const l of LEVELS)
+    for (const [id, e] of Object.entries(obj(levels[l]))) if (isValue(e?.value) && typeof e?.source === "string" && typeof e?.at === "string") d.levels[l][id] = e as Entry
+  for (const [id, k] of Object.entries(obj(raw.locks))) if (isValue(k?.value)) d.locks[id] = k
+  d.outbox = list(raw.outbox).filter(isChange)
+  d.history = list(raw.history).filter(isChange).slice(-HISTORY_MAX)
+  for (const [id, a] of Object.entries(obj(raw.applied))) if (isValue(a?.want) && typeof a?.ok === "boolean") d.applied[id] = a as Applied
+  const s = obj(raw.sync)
+  d.sync = {
+    ...(typeof s.rev === "string" ? { rev: s.rev } : {}),
+    ...(typeof s.lastSyncAt === "string" ? { lastSyncAt: s.lastSyncAt } : {}),
+    ...(typeof s.lastError === "string" ? { lastError: s.lastError } : {}),
+    ...(typeof s.machine === "string" ? { machine: s.machine } : {}),
+    refused: list(s.refused).filter((r) => r && typeof r.id === "string" && typeof r.code === "string").slice(-20),
+    held: list(s.held).filter((h) => h && typeof h.id === "string" && typeof h.why === "string").slice(-20),
+  }
+  return d
+}
+
+/**
+ * Upgrades from older layouts, one step per version (MIGRATIONS[n] turns version n into n + 1). Version 1 is the first;
+ * a file without a schema is read as version 1.
+ */
+const MIGRATIONS: Record<number, (raw: Record<string, any>) => Record<string, any>> = {}
+
+export interface ReadResult {
+  doc: SettingsDoc
+  /** The file could not be used as it is: it is not JSON, or a newer brain wrote it. */
+  problem?: "damaged" | "newer"
+}
+
+export function readSettingsFile(home: string): ReadResult {
+  const p = settingsFile(home)
+  if (!existsSync(p)) return { doc: emptyDoc() }
+  let raw: Record<string, any>
+  try {
+    raw = obj(JSON.parse(readFileSync(p, "utf8")))
+  } catch {
+    return { doc: emptyDoc(), problem: "damaged" }
+  }
+  let v = typeof raw.schema === "number" ? raw.schema : SETTINGS_SCHEMA
+  while (v < SETTINGS_SCHEMA && MIGRATIONS[v]) raw = { ...MIGRATIONS[v]!(raw), schema: ++v }
+  const doc = normalize(raw)
+  return doc.schema > SETTINGS_SCHEMA ? { doc, problem: "newer" } : { doc }
+}
+
+/** The settings as they are now (an empty document when there is no file or it cannot be read). */
+export const readDoc = (home: string): SettingsDoc => readSettingsFile(home).doc
+
+export class SettingsUnwritable extends Error {}
+
+/**
+ * Changes the document under the brain lock: reads it, lets `fn` change it, writes it back. A file a newer brain wrote is
+ * never overwritten (that would lose what it knows); a damaged one is kept aside (settings.json.damaged-<time>) first.
+ */
+export function updateDoc(home: string, fn: (d: SettingsDoc) => void): SettingsDoc {
+  return withBrainLockSync(home, () => {
+    const r = readSettingsFile(home)
+    if (r.problem === "newer") throw new SettingsUnwritable(`${settingsFile(home)} was written by a newer brain; update brain (bun add -g @100xprompt/brain) to change settings here`)
+    if (r.problem === "damaged") {
+      try {
+        renameSync(settingsFile(home), `${settingsFile(home)}.damaged-${new Date().toISOString().replace(/[:.]/g, "-")}`)
+      } catch {}
+    }
+    const d = r.doc
+    fn(d)
+    d.schema = SETTINGS_SCHEMA
+    mkdirSync(join(home, ".brain"), { recursive: true, mode: 0o700 })
+    writeAtomic(settingsFile(home), `${JSON.stringify(d, null, 1)}\n`, 0o600)
+    return d
+  })
+}
+
+export const same = (a: unknown, b: unknown) => JSON.stringify(a) === JSON.stringify(b)
+
+export interface Effective {
+  value?: Value
+  /** Where the value comes from: a lock, a level, brain's default, or nowhere (brain does not manage it). */
+  from: "lock" | Level | "default" | "none"
+  entry?: Entry
+}
+
+/**
+ * The value that applies: the team admin's lock, else the first level that has one, else the default. `accept` says which
+ * places and values count for this setting (catalog.ts: only its levels, a lock only where admins may lock, and only a
+ * value of its type); one that does not count is passed over, and the next place decides.
+ */
+export function effective(d: SettingsDoc, id: string, dflt?: Value, accept: (from: "lock" | Level, v: Value) => boolean = () => true): Effective {
+  const lock = d.locks[id]
+  if (lock && accept("lock", lock.value)) return { value: lock.value, from: "lock" }
+  for (const l of LEVELS) {
+    const e = d.levels[l][id]
+    if (e && accept(l, e.value)) return { value: e.value, from: l, entry: e }
+  }
+  return dflt === undefined ? { from: "none" } : { value: dflt, from: "default" }
+}
+
+/**
+ * Records one change: the entry at its level (removed for null), the history, and the outbox for the levels the person's
+ * account keeps (this computer's and the person's; the team's is set at the account). Nothing when it changes nothing.
+ */
+export function recordChange(d: SettingsDoc, c: Omit<Change, "replaced">, o: { upload?: boolean } = {}): Change | undefined {
+  const prev = d.levels[c.level][c.id]
+  if (c.value === null ? !prev : prev && same(prev.value, c.value) && prev.source === c.source && prev.command === c.command) return undefined
+  const change: Change = { ...c }
+  if (prev && (prev.source !== c.source || prev.command !== c.command)) change.replaced = { value: prev.value, source: prev.source, at: prev.at, ...(prev.command ? { command: prev.command } : {}) }
+  if (c.value === null) delete d.levels[c.level][c.id]
+  else d.levels[c.level][c.id] = { value: c.value, source: c.source, at: c.at, ...(c.command ? { command: c.command } : {}) }
+  d.history.push(change)
+  if (d.history.length > HISTORY_MAX) d.history.splice(0, d.history.length - HISTORY_MAX)
+  // Settings only this computer can have (privacy switches, hooks) never go to the account.
+  if (c.level !== "team" && o.upload !== false) {
+    d.outbox = d.outbox.filter((x) => !(x.id === c.id && x.level === c.level))
+    d.outbox.push(change)
+  }
+  return change
+}

package/src/settings/values.ts

@@ -0,0 +1,80 @@
+// The settings brain reads where it uses them: ways 1 and 2 (lean sessions, project memory), and the model and context
+// editing saved for a tool. Kept small and free of heavy imports, because `brain session continue`, the MCP server, the
+// session hook's memory sync and `brain gateway connect` read them on every use. catalog.ts describes the same settings
+// for `brain settings`, with the same rules for which levels and values count.
+import { effective, type Level, readSettingsFile, type SettingsDoc, type Value } from "./store.ts"
+
+/** The defaults: what brain did before these were settings (threshold: prepare.ts LEAN_AUTO_TOKENS, minChars: externalize's 1,500). */
+export const LEAN_DEFAULTS = { auto: true, threshold: 50_000, minChars: 1_500 } as const
+
+export const LIMITS = {
+  "lean.threshold": { min: 1_000, max: 2_000_000 },
+  "lean.minChars": { min: 300, max: 100_000 },
+} as const
+
+export const DEFAULTS: Record<string, Value> = {
+  "lean.auto": LEAN_DEFAULTS.auto,
+  "lean.threshold": LEAN_DEFAULTS.threshold,
+  "lean.minChars": LEAN_DEFAULTS.minChars,
+  "memory.enabled": true,
+}
+
+/** Whether a value is a valid one for this setting (a hand-edited or newer file may hold anything). */
+export function validValue(id: string, v: Value): boolean {
+  if (typeof DEFAULTS[id] === "boolean") return typeof v === "boolean"
+  const lim = LIMITS[id as keyof typeof LIMITS]
+  return typeof v === "number" && Number.isInteger(v) && (!lim || (v >= lim.min && v <= lim.max))
+}
+
+/** What a team admin's lock may hold: any value for lean, only "off" for memory. */
+const lockAllowed = (id: string, v: Value) => (id === "memory.enabled" ? v === false : id.startsWith("lean."))
+
+const valueOf = (d: SettingsDoc, id: string): Value =>
+  effective(d, id, DEFAULTS[id], (from, v) => validValue(id, v) && (from !== "lock" || lockAllowed(id, v))).value ?? DEFAULTS[id]!
+
+export interface LeanSettings {
+  /** Long sessions are made lean without --lean. */
+  auto: boolean
+  /** From this many tokens. */
+  threshold: number
+  /** Tool output longer than this many characters is replaced by a digest. */
+  minChars: number
+}
+
+export function leanSettings(home: string, d: SettingsDoc = readSettingsFile(home).doc): LeanSettings {
+  return { auto: valueOf(d, "lean.auto") as boolean, threshold: valueOf(d, "lean.threshold") as number, minChars: valueOf(d, "lean.minChars") as number }
+}
+
+/**
+ * Whether project memory is on for this computer (`brain settings set memory.enabled off` turns it off). A settings file
+ * that cannot be read counts as off: it may be the one that turned memory off, and memory can send items to a team server.
+ */
+export function memoryOn(home: string, d?: SettingsDoc): boolean {
+  if (d) return valueOf(d, "memory.enabled") as boolean
+  const r = readSettingsFile(home)
+  return r.problem === "damaged" ? false : (valueOf(r.doc, "memory.enabled") as boolean)
+}
+
+/** What brain says where memory would have been used. */
+export const MEMORY_OFF = "memory is turned off on this computer (`brain settings set memory.enabled on` turns it on)"
+
+const MODEL_LEVELS: Level[] = ["computer", "person", "team"]
+
+/**
+ * The model and context editing set for a tool with `brain settings` (or, later, the dashboard), at whatever level applies;
+ * nothing where none is set. `brain gateway connect` uses them where its flags leave them open. What connect itself recorded
+ * does not count here: a plain connect keeps doing what it always did (the last connect's settings).
+ */
+export function toolGatewayPrefs(home: string, tool: string, d: SettingsDoc = readSettingsFile(home).doc): { model?: string; contextEdit?: boolean } {
+  // The first level with a valid value decides; when that value is one a command recorded, there is no saved choice.
+  const chosen = (id: string, ok: (v: Value) => boolean) => {
+    for (const l of MODEL_LEVELS) {
+      const e = d.levels[l][id]
+      if (e && ok(e.value)) return e.source === "command" ? undefined : e.value
+    }
+    return undefined
+  }
+  const m = chosen(`tools.${tool}.model`, (v) => typeof v === "string" && ["pro", "flash", "auto"].includes(v))
+  const ce = chosen(`tools.${tool}.contextEdit`, (v) => typeof v === "boolean")
+  return { ...(typeof m === "string" ? { model: m } : {}), ...(typeof ce === "boolean" ? { contextEdit: ce } : {}) }
+}