@dirwin517/bot-farm 0.1.0

package/src/questions.mjs

@@ -0,0 +1,69 @@
+// Questions for the operator, in the shape Claude and opencode use for theirs:
+// each question may offer choices (pick one, or several), and every question
+// can also be answered in your own words. A question with no choices is just
+// open-ended.
+
+const clip = (s, n) => String(s ?? "").trim().slice(0, n)
+
+/** Strings, { question, options, multiple }, or a mix — always the same shape out. */
+export function normalizeQuestions(list) {
+  return (Array.isArray(list) ? list : list ? [list] : [])
+    .map((q) => {
+      if (typeof q === "string") return { question: clip(q, 1000), options: [], multiple: false }
+      if (!q || typeof q !== "object") return null
+      const options = (Array.isArray(q.options) ? q.options : [])
+        .map((o) => (typeof o === "string" ? { label: clip(o, 200) } : o?.label ? { label: clip(o.label, 200), description: o.description ? clip(o.description, 400) : undefined } : null))
+        .filter((o) => o?.label)
+        .slice(0, 8)
+      return {
+        question: clip(q.question ?? q.text ?? "", 1000),
+        header: q.header ? clip(q.header, 40) : undefined,
+        options,
+        multiple: !!(q.multiple ?? q.multiSelect ?? q.multi_select),
+      }
+    })
+    .filter((q) => q?.question)
+    .slice(0, 12)
+}
+
+/** The questions as plain lines, for prompts and the chat. */
+export function questionText(questions) {
+  return questions.map((q) => q.question)
+}
+
+/**
+ * Answers as text a bot can read. `answers[i]` is { picked: [labels], text }
+ * for question i; unanswered questions are said to be unanswered rather than
+ * silently dropped.
+ */
+export function formatAnswers(questions, answers = []) {
+  return questions
+    .map((q, i) => {
+      const a = answers[i] ?? {}
+      const picked = (a.picked ?? []).filter(Boolean)
+      const own = clip(a.text, 4000)
+      const said = [picked.length ? picked.join(", ") : "", own].filter(Boolean).join(" — ")
+      return `${questions.length > 1 ? `${i + 1}. ` : ""}${q.question}\n   → ${said || "(no answer — use your judgement)"}`
+    })
+    .join("\n")
+}
+
+export const QUESTION_SCHEMA = {
+  type: "object",
+  properties: {
+    question: { type: "string", description: "One thing, plainly, with enough context to answer without opening your session." },
+    header: { type: "string", description: "Optional short label (a few words)." },
+    options: {
+      type: "array",
+      description: "Concrete choices, when there are some. The operator can always answer in their own words too, so do not add an 'Other' option. Leave out for an open question.",
+      items: {
+        anyOf: [
+          { type: "string" },
+          { type: "object", properties: { label: { type: "string" }, description: { type: "string" } }, required: ["label"] },
+        ],
+      },
+    },
+    multiple: { type: "boolean", description: "True if more than one option can be picked." },
+  },
+  required: ["question"],
+}

package/src/quota.mjs

@@ -0,0 +1,76 @@
+// Per-model quotas for routing: "up to $5 a day on Opus, then Sonnet".
+//
+// Spend is kept per workspace, per model and per period in the db, in four
+// buckets at once — day, week, month and workstream — so any quota can be
+// answered with one read. Money is BotFarm's own estimate (the same pricing as
+// everywhere else); tokens are what opencode reports; minutes are time a bot
+// spent busy on that model.
+
+export const PERIODS = ["day", "week", "month", "workstream"]
+
+/** "amazon-bedrock/us.anthropic.claude-opus-5" and "claude-opus-5" are the same model for a quota. */
+export function modelKey(m) {
+  return String(m ?? "").split("/").pop().replace(/^(us|eu|apac|global)\./i, "").replace(/^anthropic\./i, "").replace(/-\d{8}(-v\d+(:\d+)?)?$/, "").toLowerCase()
+}
+
+function isoWeek(d) {
+  const t = new Date(Date.UTC(d.getFullYear(), d.getMonth(), d.getDate()))
+  const day = t.getUTCDay() || 7
+  t.setUTCDate(t.getUTCDate() + 4 - day)
+  const year = t.getUTCFullYear()
+  const week = Math.ceil(((t - Date.UTC(year, 0, 1)) / 86400_000 + 1) / 7)
+  return `${year}-W${String(week).padStart(2, "0")}`
+}
+
+export function bucketOf(per, at = Date.now(), projectId = null) {
+  const d = new Date(at)
+  const pad = (n) => String(n).padStart(2, "0")
+  if (per === "workstream") return `p:${projectId ?? "none"}`
+  if (per === "week") return `w:${isoWeek(d)}`
+  if (per === "month") return `m:${d.getFullYear()}-${pad(d.getMonth() + 1)}`
+  return `d:${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`
+}
+
+/** The first quota a spend has reached, or null. */
+export function overQuota(quota, spent) {
+  if (!quota) return null
+  for (const kind of ["usd", "tokens", "minutes"]) {
+    if (Number(quota[kind]) > 0 && (spent?.[kind] ?? 0) >= Number(quota[kind])) return { kind, limit: Number(quota[kind]), used: spent[kind] }
+  }
+  return null
+}
+
+export class ModelLedger {
+  constructor(db) {
+    this.db = db
+  }
+
+  id(wsId, model, bucket) {
+    return `${wsId ?? "none"}|${modelKey(model)}|${bucket}`
+  }
+
+  /** Also counted under `model@persona`, so an agent's own quota counts only that agent's spend. */
+  add(wsId, model, projectId, amounts = {}, at = Date.now(), persona = null) {
+    this.addOne(wsId, model, projectId, amounts, at)
+    if (persona) this.addOne(wsId, `${modelKey(model)}@${persona}`, projectId, amounts, at)
+  }
+
+  addOne(wsId, model, projectId, { usd = 0, tokens = 0, minutes = 0 } = {}, at = Date.now()) {
+    if (!model || (!usd && !tokens && !minutes)) return
+    for (const per of PERIODS) {
+      if (per === "workstream" && !projectId) continue
+      const id = this.id(wsId, model, bucketOf(per, at, projectId))
+      const row = this.db.get("modelspend", id) ?? { id, ws: wsId ?? null, model: modelKey(model), bucket: bucketOf(per, at, projectId), usd: 0, tokens: 0, minutes: 0 }
+      row.usd += usd
+      row.tokens += tokens
+      row.minutes += minutes
+      row.updated = at
+      this.db.put("modelspend", row)
+    }
+  }
+
+  spent(wsId, model, per = "day", projectId = null, at = Date.now()) {
+    const row = this.db.get("modelspend", this.id(wsId, model, bucketOf(per, at, projectId)))
+    return { usd: row?.usd ?? 0, tokens: row?.tokens ?? 0, minutes: row?.minutes ?? 0 }
+  }
+}

package/src/registry.mjs

@@ -0,0 +1,88 @@
+// botfarm only manages sessions you put on the board.
+//
+// `opencode` accumulates every session you have ever opened; listing them all
+// turns the dashboard into an archive browser. The registry is the line
+// between "a session that exists" and "a session I am running right now",
+// and it is also where botfarm keeps the metadata opencode has no place for:
+// group, label, notes, mesh policy, lineage.
+
+import { readFile, writeFile, mkdir } from "node:fs/promises"
+import { dirname } from "node:path"
+
+export class Registry {
+  constructor(path) {
+    this.path = path
+    this.entries = new Map() // sessionId -> { group, label, notes, adoptedAt, createdByBotfarm }
+    this.groups = ["default"]
+  }
+
+  async load() {
+    try {
+      const raw = JSON.parse(await readFile(this.path, "utf8"))
+      this.entries = new Map(Object.entries(raw.sessions ?? {}))
+      this.groups = raw.groups?.length ? raw.groups : ["default"]
+    } catch {}
+  }
+
+  async save() {
+    await mkdir(dirname(this.path), { recursive: true })
+    await writeFile(
+      this.path,
+      JSON.stringify({ sessions: Object.fromEntries(this.entries), groups: this.groups }, null, 2),
+    )
+  }
+
+  has(id) {
+    return this.entries.has(id)
+  }
+
+  get(id) {
+    return this.entries.get(id) ?? null
+  }
+
+  adopt(id, meta = {}) {
+    const existing = this.entries.get(id) ?? {}
+    const entry = {
+      group: "default",
+      label: null,
+      notes: "",
+      createdByBotfarm: false,
+      adoptedAt: Date.now(),
+      ...existing,
+      ...meta,
+    }
+    this.entries.set(id, entry)
+    if (entry.group && !this.groups.includes(entry.group)) this.groups.push(entry.group)
+    return entry
+  }
+
+  release(id) {
+    this.entries.delete(id)
+  }
+
+  update(id, patch) {
+    const entry = this.entries.get(id)
+    if (!entry) return null
+    Object.assign(entry, patch)
+    if (patch.group && !this.groups.includes(patch.group)) this.groups.push(patch.group)
+    return entry
+  }
+
+  addGroup(name) {
+    const clean = String(name).trim().slice(0, 32)
+    if (clean && !this.groups.includes(clean)) this.groups.push(clean)
+    return clean
+  }
+
+  removeGroup(name) {
+    if (name === "default") return
+    this.groups = this.groups.filter((g) => g !== name)
+    for (const e of this.entries.values()) if (e.group === name) e.group = "default"
+  }
+
+  counts() {
+    const out = Object.fromEntries(this.groups.map((g) => [g, 0]))
+    for (const e of this.entries.values()) out[e.group] = (out[e.group] ?? 0) + 1
+    return out
+  }
+}

package/src/replay.mjs

@@ -0,0 +1,151 @@
+// Replays: everything that happened in a workstream, as a timeline you can
+// scrub through later — or save as one file and open on another computer.
+//
+// While a workstream runs, small events are appended to
+// <workspace>/.botfarm/workstreams/<id>.replay.jsonl (buffered, a line each):
+//
+//   { t, k: "task", task: { id, title, stage, status, assignee, parentId, item, kind, owner } }
+//   { t, k: "bot",  bot: { id, handle, persona, personaTitle, status, tool } }
+//   { t, k: "msg",  msg: { id, from, fromId, text } }
+//   { t, k: "note", text, level }
+//   { t, k: "harvest", harvest }
+//
+// An export bundles that with the workstream's header into a single JSON
+// document ("botfarm-replay", version 1). Avatars are drawn from id + handle,
+// so a replay needs nothing from the machine that recorded it.
+
+import { appendFile, readFile, mkdir, writeFile, readdir } from "node:fs/promises"
+import { join, dirname } from "node:path"
+
+export const REPLAY_FORMAT = "botfarm-replay"
+
+const pickTask = (t) => ({ id: t.id, title: t.title, stage: t.stage ?? null, status: t.status, assignee: t.assignee ?? null, parentId: t.parentId ?? null, item: t.item ?? null, kind: t.kind ?? "work", owner: t.owner ?? null, order: t.order ?? 0, children: t.children ?? null, dependsOn: t.dependsOn ?? [] })
+const pickBot = (s) => ({ id: s.id, handle: s.handle, persona: s.persona ?? null, personaTitle: s.personaTitle ?? null, status: s.status, tool: s.currentTool?.name ?? null })
+
+export class Recorder {
+  constructor({ pathFor }) {
+    this.pathFor = pathFor // (projectId) => file path, or null when it has no workspace
+    this.buf = new Map() // path -> lines
+    this.last = new Map() // `${projectId}:${kind}:${id}` -> signature, to record changes only
+    this.timer = setInterval(() => this.flush().catch(() => {}), 2000)
+    this.timer.unref?.()
+  }
+
+  push(projectId, ev) {
+    if (!projectId || projectId === "default") return
+    const path = this.pathFor(projectId)
+    if (!path) return
+    const line = JSON.stringify({ t: Date.now(), ...ev })
+    this.buf.set(path, [...(this.buf.get(path) ?? []), line])
+  }
+
+  /** Record a task only when something visible about it changed. */
+  task(t) {
+    if (!t?.projectId) return
+    const snap = pickTask(t)
+    const sig = JSON.stringify([snap.status, snap.assignee, snap.title, snap.children?.length])
+    const key = `${t.projectId}:task:${t.id}`
+    if (this.last.get(key) === sig) return
+    this.last.set(key, sig)
+    this.push(t.projectId, { k: "task", task: snap })
+  }
+
+  bot(s) {
+    if (!s?.project) return
+    const snap = pickBot(s)
+    const sig = JSON.stringify([snap.status, snap.tool, snap.handle])
+    const key = `${s.project}:bot:${s.id}`
+    if (this.last.get(key) === sig) return
+    this.last.set(key, sig)
+    this.push(s.project, { k: "bot", bot: snap })
+  }
+
+  msg(projectId, m) {
+    this.push(projectId, { k: "msg", msg: { id: m.id, from: m.from, fromId: m.fromId ?? null, text: String(m.text).slice(0, 4000) } })
+  }
+
+  note(projectId, text, level = "info") {
+    this.push(projectId, { k: "note", text: String(text).slice(0, 400), level })
+  }
+
+  harvest(projectId, h) {
+    this.push(projectId, { k: "harvest", harvest: h })
+  }
+
+  async flush() {
+    for (const [path, lines] of [...this.buf]) {
+      this.buf.delete(path)
+      if (!lines.length) continue
+      await mkdir(dirname(path), { recursive: true }).catch(() => {})
+      await appendFile(path, lines.join("\n") + "\n").catch(() => {})
+    }
+  }
+
+  async events(projectId) {
+    await this.flush()
+    const path = this.pathFor(projectId)
+    if (!path) return []
+    const text = await readFile(path, "utf8").catch(() => "")
+    return text.split("\n").filter(Boolean).map((l) => { try { return JSON.parse(l) } catch { return null } }).filter(Boolean)
+  }
+
+  stop() {
+    clearInterval(this.timer)
+    return this.flush()
+  }
+}
+
+/** One portable document for a workstream. */
+export function bundle({ project, run, team, tasks, messages, events, harvest = null }) {
+  const start = Math.min(...[run?.created, project?.created, events[0]?.t].filter(Boolean)) || Date.now()
+  // Seed the timeline with the state at the start, so a replay recorded
+  // mid-way (or before recording existed) still has a board to show.
+  const seeded = [
+    ...team.map((s) => ({ t: start, k: "bot", bot: pickBot({ ...s, status: "idle", currentTool: null }) })),
+    ...tasks.filter((t) => !events.some((e) => e.k === "task" && e.task.id === t.id)).map((t) => ({ t: t.created ?? start, k: "task", task: pickTask(t) })),
+    ...messages.filter((m) => !events.some((e) => e.k === "msg" && e.msg.id === m.id)).map((m) => ({ t: m.at, k: "msg", msg: { id: m.id, from: m.from, fromId: m.fromId ?? null, text: m.text } })),
+  ]
+  const all = [...seeded, ...events].sort((a, b) => a.t - b.t)
+  return {
+    format: REPLAY_FORMAT,
+    version: 1,
+    exportedAt: new Date().toISOString(),
+    project: { id: project.id, name: project.name, branch: project.branch ?? null, story: project.story ?? null, pipeline: project.pipelineTitle ?? project.pipeline ?? null },
+    team: team.map((s) => ({ id: s.id, handle: s.handle, persona: s.persona ?? null, personaTitle: s.personaTitle ?? null, model: s.model ?? s.configuredModel ?? null })),
+    start,
+    end: all.at(-1)?.t ?? start,
+    harvest,
+    events: all,
+  }
+}
+
+export function validBundle(doc) {
+  return doc && doc.format === REPLAY_FORMAT && Array.isArray(doc.events) && doc.project?.name
+}
+
+/** Imported replays live in ~/.botfarm/replays, one file each. */
+export class ReplayShelf {
+  constructor(dir) { this.dir = dir }
+  async list() {
+    const names = await readdir(this.dir).catch(() => [])
+    const out = []
+    for (const n of names.filter((x) => x.endsWith(".json"))) {
+      try {
+        const d = JSON.parse(await readFile(join(this.dir, n), "utf8"))
+        out.push({ id: n.replace(/\.json$/, ""), name: d.project?.name, start: d.start, end: d.end, events: d.events?.length ?? 0, importedFrom: d.importedFrom ?? null })
+      } catch {}
+    }
+    return out.sort((a, b) => (b.end ?? 0) - (a.end ?? 0))
+  }
+  async get(id) {
+    if (!/^[\w.-]+$/.test(id)) throw new Error("bad replay id")
+    return JSON.parse(await readFile(join(this.dir, `${id}.json`), "utf8"))
+  }
+  async put(doc) {
+    if (!validBundle(doc)) throw new Error("that is not a BotFarm replay file")
+    const id = `${String(doc.project.name).toLowerCase().replace(/[^a-z0-9]+/g, "-").slice(0, 40)}-${Date.now().toString(36)}`
+    await mkdir(this.dir, { recursive: true })
+    await writeFile(join(this.dir, `${id}.json`), JSON.stringify(doc))
+    return id
+  }
+}