@a-t-h-i/bot-lobby 0.6.6 → 0.6.8

package/src/lobby/knowledge.ts

@@ -0,0 +1,179 @@
+/**
+ * The Knowledge tab's side of the disk: every agent's knowledge files, one
+ * file read as entries with the user's notes on them, and the edits the user
+ * can make — replace, add or delete an entry, edit the whole file — plus
+ * notes. Every write goes through the compactor's path, which archives the
+ * previous version first (`archive/<Agent>/…bak`), so an edit can be undone by
+ * hand. An entry is found again by its exact text; when the file changed on
+ * disk since the tab drew it, the edit is refused with a line saying so.
+ */
+import { join } from "node:path";
+import { compactKnowledgeFile } from "../knowledge/compactor.ts";
+import { findEntry, insertAfter, parseEntries, removeEntry, replaceEntry, type KnowledgeEntry } from "../knowledge/edit.ts";
+import { addNote, moveNotes, readNotes, removeNote, removeNotesOn, type KnowledgeNote } from "../knowledge/notes.ts";
+import { AGENT_DIR_NAMES, KNOWLEDGE_FILES, knowledgeDir, type KnowledgeAgent } from "../knowledge/paths.ts";
+import { readFirstExisting } from "../knowledge/store.ts";
+import { dataRoot, readDataRoots } from "../state/project.ts";
+
+/** What each knowledge file is, in words. */
+export const FILE_LABELS: Record<string, string> = {
+  "knowledge.md": "Knowledge",
+  "decisions.md": "Decisions",
+  "completed-tasks.md": "Completed tasks",
+  "standards.md": "Standards",
+  "design-language.md": "Design language",
+  "engineering-standards.md": "Engineering standards",
+  "testing-standards.md": "Testing standards",
+};
+
+/** Who the agents are, as the lobby names them. */
+export const AGENT_LABELS: Record<KnowledgeAgent, string> = { master: "Master (oracle)", designer: "Designer", backend: "Backend", qa: "QA" };
+
+export interface KnowledgeFileInfo {
+  agent: KnowledgeAgent;
+  file: string;
+  label: string;
+  chars: number;
+  /** Past the compaction threshold: the Master should compact it. */
+  over: boolean;
+  notes: number;
+}
+
+export interface KnowledgeView extends KnowledgeFileInfo {
+  content: string;
+  entries: KnowledgeEntry[];
+  /** Notes on entries this file has. */
+  attached: KnowledgeNote[];
+  /** Notes whose entry has changed or gone: kept, shown apart. */
+  detached: KnowledgeNote[];
+}
+
+/** An entry picked in the tab: its text, and which of several identical ones it is. */
+export interface EntryRef {
+  text: string;
+  occurrence: number;
+}
+
+export interface KnowledgeDeps {
+  root: string;
+  configDir: string;
+  /** Characters past which a file is over its compaction threshold. */
+  threshold: () => number;
+  /** Backups of a file kept in the archive. */
+  backups: () => number;
+  sessionId?: () => string | undefined;
+  now?: () => Date;
+}
+
+const CHANGED = "that entry changed on disk since it was drawn — r reloads the file";
+
+export class KnowledgeBook {
+  private readonly deps: KnowledgeDeps;
+
+  constructor(deps: KnowledgeDeps) {
+    this.deps = deps;
+  }
+
+  private get data(): string {
+    return dataRoot(this.deps.root, this.deps.configDir);
+  }
+
+  private read(agent: KnowledgeAgent, file: string): string {
+    return readFirstExisting(readDataRoots(this.deps.root, this.deps.configDir).map((root) => join(knowledgeDir(root, agent), file)));
+  }
+
+  /** Every agent's files in the order the tab lists them, with their size and notes. */
+  files(): KnowledgeFileInfo[] {
+    const notes = readNotes(this.data);
+    return (Object.keys(AGENT_DIR_NAMES) as KnowledgeAgent[]).flatMap((agent) =>
+      KNOWLEDGE_FILES[agent].map((file) => {
+        const chars = this.read(agent, file).length;
+        return { agent, file, label: FILE_LABELS[file] ?? file, chars, over: chars > this.deps.threshold(), notes: notes.filter((note) => note.agent === agent && note.file === file).length };
+      }),
+    );
+  }
+
+  /** One file as entries with their notes. */
+  open(agent: KnowledgeAgent, file: string): KnowledgeView {
+    const content = this.read(agent, file);
+    const entries = parseEntries(content);
+    const notes = readNotes(this.data).filter((note) => note.agent === agent && note.file === file);
+    const known = new Set(entries.map((entry) => entry.text));
+    return {
+      agent,
+      file,
+      label: FILE_LABELS[file] ?? file,
+      chars: content.length,
+      over: content.length > this.deps.threshold(),
+      notes: notes.length,
+      content,
+      entries,
+      attached: notes.filter((note) => known.has(note.entry)),
+      detached: notes.filter((note) => !known.has(note.entry)),
+    };
+  }
+
+  /** Write a file's new content with the previous one archived; the notice says where it went. */
+  private write(agent: KnowledgeAgent, file: string, content: string): string {
+    compactKnowledgeFile({ dataRoot: this.data, agent, file, content, backupCount: this.deps.backups(), ...(this.deps.now ? { now: this.deps.now() } : {}) });
+    return `saved ${agent}/${file} — the version before is in archive/${AGENT_DIR_NAMES[agent]}`;
+  }
+
+  /** Replace one entry with `text`, exactly as written; its notes move with it. */
+  edit(agent: KnowledgeAgent, file: string, ref: EntryRef, text: string): string {
+    const content = this.read(agent, file);
+    const entry = findEntry(content, ref.text, ref.occurrence);
+    if (!entry) return CHANGED;
+    if (!text.trim()) return "nothing to save — d d deletes an entry, esc cancels";
+    const next = replaceEntry(content, entry, text);
+    if (next.trim() === content.trim()) return "nothing changed";
+    const notice = this.write(agent, file, next);
+    const moved = moveNotes(this.data, agent, file, entry.text, text.replace(/\s+$/, ""), this.deps.now?.());
+    return `${notice}${moved > 0 ? `; ${moved} note${moved === 1 ? "" : "s"} stayed with it` : ""}`;
+  }
+
+  /** Add a bullet after an entry (at the end when there is none). */
+  add(agent: KnowledgeAgent, file: string, after: EntryRef | undefined, text: string): string {
+    const content = this.read(agent, file);
+    const entry = after ? findEntry(content, after.text, after.occurrence) : undefined;
+    if (after && !entry) return CHANGED;
+    const next = insertAfter(content, entry, text);
+    if (next === content) return "nothing to add";
+    return this.write(agent, file, next);
+  }
+
+  /** Delete an entry, and the notes on it. */
+  remove(agent: KnowledgeAgent, file: string, ref: EntryRef): string {
+    const content = this.read(agent, file);
+    const entry = findEntry(content, ref.text, ref.occurrence);
+    if (!entry) return CHANGED;
+    const notice = this.write(agent, file, removeEntry(content, entry));
+    const gone = removeNotesOn(this.data, agent, file, entry.text, this.deps.now?.());
+    return `${notice}${gone > 0 ? `; its ${gone} note${gone === 1 ? "" : "s"} went with it` : ""}`;
+  }
+
+  /** Replace a whole file (edited in pi's editor). */
+  replaceFile(agent: KnowledgeAgent, file: string, text: string): string {
+    const content = this.read(agent, file);
+    if (text.trim() === content.trim()) return "nothing changed";
+    return this.write(agent, file, text);
+  }
+
+  /** Leave a note on an entry: every agent that reads this knowledge reads it under the entry. */
+  comment(agent: KnowledgeAgent, file: string, ref: EntryRef, text: string): string {
+    const entry = findEntry(this.read(agent, file), ref.text, ref.occurrence);
+    if (!entry) return CHANGED;
+    try {
+      addNote(this.data, { agent, file, entry: entry.text, text, ...(this.deps.sessionId?.() ? { by: this.deps.sessionId!()! } : {}) }, this.deps.now?.());
+    } catch (error) {
+      return (error as Error).message;
+    }
+    return "note saved — every agent reads it under this entry";
+  }
+
+  /** Take a note back. */
+  unnote(id: string): string {
+    removeNote(this.data, id, this.deps.now?.());
+    return "note removed";
+  }
+}

package/src/lobby/layout.ts

@@ -91,6 +91,9 @@ export function wrapHanging(lead: string, text: string, width: number): string[]
   return body.map((line, index) => `${index === 0 ? lead : " ".repeat(indent)}${line}`);
 }
 
+/** The mark before a git branch name, in the lobby's title and a task's details. */
+export const BRANCH_GLYPH = "⎇";
+
 /** `── Title ───────` spanning `width`; `right` sits at the far end when it fits. */
 export function rule(width: number, title = "", theme?: LobbyTheme, right = "", color: LobbyColor = "borderMuted"): string {
   if (width <= 0) return "";
@@ -268,6 +271,87 @@ export function scrollThumb(total: number, rows: number, start: number): { from:
   return { from, to: from + size };
 }
 
+/** Lines a page moves a pane: its rows less one, so a line of context carries over. */
+export function pageStep(rows: number): number {
+  return Math.max(1, rows - 1);
+}
+
+/** How many pages a pane showing `rows` lines at a time holds out of `total`. */
+export function pageCount(total: number, rows: number): number {
+  return total <= rows ? 1 : 1 + Math.ceil((total - rows) / pageStep(rows));
+}
+
+/**
+ * The page a pane showing lines from `start` is on, counted so that the top is
+ * page 1 and the bottom the last, and a page's worth of scrolling from either
+ * end lands exactly on the next number: a log that opens at its newest line
+ * and a detail that opens at its first both step through the same numbers.
+ */
+export function pageOf(total: number, rows: number, start: number): number {
+  const end = Math.max(0, total - rows);
+  const behind = Math.ceil(Math.max(0, end - Math.max(0, start)) / pageStep(rows));
+  return Math.max(1, pageCount(total, rows) - behind);
+}
+
+/** One piece of the pager: a button, where the pane is, or what sits between them. */
+export interface PagerPart {
+  text: string;
+  role: "up" | "down" | "where" | "between";
+}
+
+/** Fewest columns of border kept either side of the pager, beside its two spaces. */
+const PAGER_MARGIN = 3;
+
+/**
+ * The pager in a scrolling pane's bottom border, as words a newcomer can read:
+ * `▲ prev · page 2/5 · next ▼`, shortening to `▲ prev · 2/5 · next ▼` and
+ * `▲ 2/5 ▼` as the pane narrows, and to nothing when even that will not fit
+ * in `room` columns. The page number is padded to the width of the page count,
+ * so the buttons stay where they are as it changes and a click can be traced
+ * from the pane's size alone.
+ */
+export function pager(total: number, rows: number, start: number, room: number): PagerPart[] | undefined {
+  const pages = pageCount(total, rows);
+  const count = String(pages);
+  const of = `${String(pageOf(total, rows, start)).padStart(count.length)}/${pages}`;
+  const between = (text: string): PagerPart => ({ text, role: "between" });
+  const up = (text: string): PagerPart => ({ text, role: "up" });
+  const down = (text: string): PagerPart => ({ text, role: "down" });
+  const where = (text: string): PagerPart => ({ text, role: "where" });
+  const variants: PagerPart[][] = [
+    [up("▲ prev"), between(" · "), where(`page ${of}`), between(" · "), down("next ▼")],
+    [up("▲ prev"), between(" · "), where(of), between(" · "), down("next ▼")],
+    [up("▲"), between(" "), where(of), between(" "), down("▼")],
+  ];
+  return variants.find((parts) => parts.reduce((sum, part) => sum + textWidth(part.text), 0) <= room);
+}
+
+/** Columns a box of `width` leaves for the pager's text: two spaces around it and a margin of border on each side. */
+function pagerRoom(width: number): number {
+  return width - 2 - 2 - PAGER_MARGIN;
+}
+
+/**
+ * Which button a column of a scrollable pane's bottom border is: -1 (a page
+ * up) or 1 (a page down), or undefined. The buttons take their words and the
+ * space beside them, so a click a little off still lands.
+ */
+export function pagerButton(width: number, column: number, total: number, rows: number): -1 | 1 | undefined {
+  const parts = pager(total, rows, 0, pagerRoom(width));
+  if (!parts) return undefined;
+  const size = parts.reduce((sum, part) => sum + textWidth(part.text), 0);
+  // The text ends one space before the corner: `… next ▼ ╯`.
+  const origin = width - 2 - size;
+  let at = origin;
+  for (const part of parts) {
+    const from = part.role === "up" ? origin - 1 : at;
+    const to = part.role === "down" ? width - 1 : at + textWidth(part.text);
+    if (column >= from && column < to) return part.role === "up" ? -1 : part.role === "down" ? 1 : undefined;
+    at += textWidth(part.text);
+  }
+  return undefined;
+}
+
 /**
  * A rounded panel exactly `width` × `height`: the title set into the top
  * border, `content` inside with one column of padding, extra lines cut and
@@ -291,7 +375,21 @@ export function box(width: number, height: number, content: readonly string[], o
   const thumb = options.scroll ? scrollThumb(options.scroll.total, height - 2, options.scroll.start) : undefined;
   const rightEdge = (row: number) => (thumb && row >= thumb.from && row < thumb.to ? paint(theme, focused ? "accent" : "muted", "┃") : edge("│"));
   const rows = fill(content, height - 2).map((line, row) => `${edge("│")} ${fit(line, inner)} ${rightEdge(row)}`);
-  return [top, ...rows, `${edge("╰")}${edge("─".repeat(width - 2))}${edge("╯")}`];
+  // A pane with more lines than rows carries a pager in its bottom border; `pagerButton` finds its buttons again for clicks.
+  const parts = thumb && options.scroll ? pager(options.scroll.total, height - 2, options.scroll.start, pagerRoom(width)) : undefined;
+  const atTop = (options.scroll?.start ?? 0) <= 0;
+  const atEnd = options.scroll ? options.scroll.start >= options.scroll.total - (height - 2) : true;
+  const paintPart = (part: PagerPart): string => {
+    if (part.role === "between") return paint(theme, "dim", part.text);
+    if (part.role === "where") return paint(theme, focused ? "text" : "muted", part.text);
+    // A button that cannot go further is dimmed: the pane is at that end.
+    if (part.role === "up" ? atTop : atEnd) return paint(theme, "dim", part.text);
+    return bold(theme, paint(theme, focused ? "accent" : "text", part.text));
+  };
+  const pagerText = parts ? ` ${parts.map(paintPart).join("")} ` : "";
+  const pagerWidth = parts ? parts.reduce((sum, part) => sum + textWidth(part.text), 0) + 2 : 0;
+  const bottom = `${edge("╰")}${edge("─".repeat(width - 2 - pagerWidth))}${pagerText}${edge("╯")}`;
+  return [top, ...rows, bottom];
 }
 
 /** Lay boxes out side by side, each already exactly its width and the same height. */

package/src/lobby/mini.ts

@@ -0,0 +1,159 @@
+/**
+ * The one-line status shown under pi's editor while the lobby is hidden: a
+ * small graphic of where the work stands — the task's plan steps (or its stage
+ * before there is a plan), the planning rounds, the quick fix in hand — or a
+ * quiet "idle". Pure: everything it shows arrives as input.
+ */
+import { truncateToWidth } from "@earendil-works/pi-tui";
+import type { AgentRun } from "../schemas/findings.ts";
+import type { Task, TaskState } from "../schemas/task.ts";
+import { planChecklist } from "../pi/plan-checklist.ts";
+import { agentName } from "../pi/run-summary.ts";
+import { paint, type LobbyTheme } from "./layout.ts";
+
+export interface MiniPlanning {
+  /** A round is running. */
+  busy: boolean;
+  /** The round in hand, and the limit (0 = unlimited). */
+  round: number;
+  limit: number;
+  /** Questions waiting for the user. */
+  questions: number;
+  /** The oracle's draft is ready to save. */
+  ready: boolean;
+  /** The plan was saved as a pending task. */
+  saved: boolean;
+}
+
+export interface MiniQuickFix {
+  title: string;
+  running: boolean;
+  queued: number;
+}
+
+export interface MiniInput {
+  task?: Task;
+  runs: readonly AgentRun[];
+  planning?: MiniPlanning;
+  quickfix?: MiniQuickFix;
+  /** The key that opens the lobby, as shown. */
+  key: string;
+}
+
+/** A full-workflow task's stages, in order, for the strip shown before its plan has steps. */
+const STAGES: readonly TaskState[] = ["clarifying", "scouting", "synthesizing", "awaiting_approval", "planning", "implementing", "reviewing"];
+
+/** Widest step bar; longer plans share its cells. */
+const MAX_CELLS = 12;
+
+/** `■■◐□□`: the plan's steps done, current and to do, squeezed into at most `MAX_CELLS` cells. */
+export function stepBar(statuses: readonly ("done" | "current" | "pending")[]): string {
+  if (statuses.length === 0) return "";
+  const cells = Math.min(statuses.length, MAX_CELLS);
+  const out: string[] = [];
+  for (let cell = 0; cell < cells; cell += 1) {
+    const from = Math.floor((cell * statuses.length) / cells);
+    const to = Math.max(from + 1, Math.floor(((cell + 1) * statuses.length) / cells));
+    const slice = statuses.slice(from, to);
+    out.push(slice.every((status) => status === "done") ? "■" : slice.some((status) => status === "current") ? "◐" : slice.some((status) => status === "done") ? "◐" : "□");
+  }
+  return out.join("");
+}
+
+/** `●●◐○○○○`: how far along the workflow a task without a plan yet is. */
+export function stageBar(state: TaskState): string {
+  const at = STAGES.indexOf(state);
+  if (at < 0) return "";
+  return STAGES.map((_stage, index) => (index < at ? "●" : index === at ? "◐" : "○")).join("");
+}
+
+/** `■■□□□` for `round` of `limit`, or empty without a limit. */
+function roundBar(round: number, limit: number): string {
+  if (limit <= 0) return "";
+  const done = Math.min(limit, Math.max(0, round));
+  return "■".repeat(done) + "□".repeat(limit - done);
+}
+
+const STATE_WORDS: Partial<Record<TaskState, string>> = {
+  awaiting_approval: "awaiting your approval",
+};
+
+function taskSegment(input: MiniInput, theme?: LobbyTheme): string | undefined {
+  const task = input.task;
+  if (!task || task.state === "completed" || task.state === "abandoned") return undefined;
+  const steps = task.plan ? planChecklist(task.plan, input.runs) : [];
+  const done = steps.filter((step) => step.status === "done").length;
+  const bar = steps.length > 0 ? `${stepBar(steps.map((step) => step.status))} ${done}/${steps.length}` : stageBar(task.state);
+  const state = task.paused ? `${task.state} (paused)` : STATE_WORDS[task.state] ?? task.state;
+  const running = [...input.runs].reverse().find((run) => run.status === "running");
+  const doing = running ? ` · ${agentName(running)}${running.activity ? ` ${running.activity}` : ""}` : "";
+  const alert = task.state === "awaiting_approval" || task.paused;
+  return `${paint(theme, "accent", task.id)} ${paint(theme, "success", bar)} ${paint(theme, alert ? "warning" : "muted", state)}${paint(theme, "dim", doing)}`;
+}
+
+function planningSegment(planning: MiniPlanning | undefined, theme?: LobbyTheme): string | undefined {
+  if (!planning || planning.saved) return undefined;
+  const rounds = roundBar(planning.round, planning.limit);
+  const head = `${paint(theme, "accent", "planning")} ${paint(theme, "success", rounds || `round ${planning.round}`)}${rounds ? paint(theme, "muted", ` ${planning.round}/${planning.limit}`) : ""}`;
+  if (planning.questions > 0) return `${head} ${paint(theme, "warning", `● ${planning.questions} question${planning.questions === 1 ? "" : "s"} for you`)}`;
+  if (planning.busy) return `${head} ${paint(theme, "muted", "the panel is thinking")}`;
+  if (planning.ready) return `${head} ${paint(theme, "success", "plan ready to save")}`;
+  return head;
+}
+
+function quickFixSegment(quickfix: MiniQuickFix | undefined, theme?: LobbyTheme): string | undefined {
+  if (!quickfix) return undefined;
+  const queued = quickfix.queued > 0 ? ` +${quickfix.queued} queued` : "";
+  return `${paint(theme, "accent", "quick fix")} ${paint(theme, "success", quickfix.running ? "◐" : "○")} ${paint(theme, "muted", quickfix.title)}${paint(theme, "dim", queued)}`;
+}
+
+/** The status line, at most `width` columns. */
+export function miniLine(input: MiniInput, width: number, theme?: LobbyTheme): string {
+  if (width < 12) return "";
+  const segments = [taskSegment(input, theme), planningSegment(input.planning, theme), quickFixSegment(input.quickfix, theme)].filter((segment): segment is string => Boolean(segment));
+  const body = segments.length > 0 ? segments.join(paint(theme, "dim", "  │  ")) : paint(theme, "dim", "idle");
+  const hint = paint(theme, "dim", `  ${input.key} opens`);
+  const line = ` ${paint(theme, "accent", "◆ bot-lobby")}  ${body}`;
+  return truncateToWidth(`${line}${hint}`, width, "…");
+}
+
+/** An agent at work right now, for the lobby's bottom-line indicator. */
+export interface WorkingAgent {
+  name: string;
+  activity?: string;
+  /** Epoch ms it started, for its elapsed time. */
+  since?: number;
+}
+
+/** The subagents running now: task runs still going, and the quick fix in hand. */
+export function workingAgents(runs: readonly AgentRun[], quickFix?: { startedAt?: number }): WorkingAgent[] {
+  const agents: WorkingAgent[] = [];
+  for (const run of runs) {
+    if (run.status !== "running") continue;
+    const since = Date.parse(run.startedAt);
+    agents.push({ name: agentName(run), ...(run.activity ? { activity: run.activity } : {}), ...(Number.isFinite(since) ? { since } : {}) });
+  }
+  if (quickFix) agents.push({ name: "QUICK FIX", ...(quickFix.startedAt ? { since: quickFix.startedAt } : {}) });
+  return agents;
+}
+
+function elapsed(ms: number): string {
+  const seconds = Math.max(0, Math.floor(ms / 1000));
+  return seconds < 60 ? `${seconds}s` : `${Math.floor(seconds / 60)}m`;
+}
+
+/**
+ * `◐ DESIGN editing 2m · DEV running 40s`, at most `width` columns: it gives up
+ * the activity and time, then the names, then shows only a count, and nothing
+ * when even that does not fit or nothing is working. `spin` is the spinner glyph.
+ */
+export function agentsIndicator(agents: readonly WorkingAgent[], now: number, spin: string, width: number, theme?: LobbyTheme): string {
+  if (agents.length === 0) return "";
+  const full = agents.map((agent) => `${agent.name}${agent.activity ? ` ${agent.activity}` : ""}${agent.since ? ` ${elapsed(now - agent.since)}` : ""}`).join(" · ");
+  const names = [...new Set(agents.map((agent) => agent.name))].join(" · ");
+  const count = `${agents.length} agent${agents.length === 1 ? "" : "s"} working`;
+  for (const text of [full, names, count]) {
+    if (text.length + 2 <= width) return `${paint(theme, "accent", spin)} ${paint(theme, "muted", text)}`;
+  }
+  return "";
+}