@a-t-h-i/bot-lobby 0.6.2 → 0.6.3

package/src/pi/zen.ts

@@ -7,7 +7,7 @@
  * arrive on its run. Everything here is pure: expression frames and the spinner
  * tick arrive from the caller, and every timestamp arrives as `now`.
  */
-import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { clip, textWidth } from "../width.ts";
 import type { AgentRun } from "../schemas/findings.ts";
 import { TERMINAL_STATES, type Task, type TaskState } from "../schemas/task.ts";
 import { truncate } from "../text.ts";
@@ -399,9 +399,9 @@ const BANNER_MIN_WIDTH = 60;
 /** Boxed title for wide terminals, one-line title otherwise; never wider than `width`. */
 export function bannerLines(width: number): string[] {
   if (width < 1) return [];
-  if (width < BANNER_MIN_WIDTH) return [truncateToWidth(BANNER_NARROW, width, "")];
+  if (width < BANNER_MIN_WIDTH) return [clip(BANNER_NARROW, width, "")];
   const inner = BANNER_WIDTH - 2;
-  const titleWidth = visibleWidth(BANNER_TITLE);
+  const titleWidth = textWidth(BANNER_TITLE);
   const left = Math.floor((inner - titleWidth) / 2);
   const border = "─".repeat(inner);
   return [`┌${border}┐`, `│${" ".repeat(left)}${BANNER_TITLE}${" ".repeat(inner - titleWidth - left)}│`, `└${border}┘`];
@@ -476,7 +476,7 @@ function compactFrame(slot: SlotView, expressions: ExpressionFrames): string {
 }
 
 function compactRow(content: string, color: PanelColor, theme?: PanelTheme): string {
-  const body = truncateToWidth(content, COMPACT_INNER, "", true);
+  const body = clip(content, COMPACT_INNER, "", true);
   return `|${theme ? theme.fg(color, body) : body}|`;
 }
 
@@ -524,7 +524,7 @@ function compactPanel(
   const fixed = [...bannerLines(width), headerLine(task, now, quiet), ...strip];
   const tail = tailLines(task, runs, now, tick, steps, opts.theme);
   const room = Math.max(0, MAX_PANEL_LINES - fixed.length - tail.length);
-  return [...fixed, ...tail, ...checklistLines(steps, room)].map((line) => truncateToWidth(line, width));
+  return [...fixed, ...tail, ...checklistLines(steps, room)].map((line) => clip(line, width));
 }
 
 /* -------------------------------------------------------------------------
@@ -646,7 +646,7 @@ export function panelLines(
   // The still scene has no tower or agent strip to fit, so any height keeps the large tier's status box.
   if (width >= LARGE_MIN_WIDTH && (budget >= MIN_LARGE_LINES || opts.still)) {
     const scene = largeLines(sceneInput(task, runs, now, quiet, tick, steps, opts), width, budget, opts.theme, opts.still);
-    return scene.map((line) => truncateToWidth(line, width));
+    return scene.map((line) => clip(line, width));
   }
   return compactPanel(task, runs, now, quiet, tick, steps, opts, width);
 }

package/src/schemas/configuration.ts

@@ -66,6 +66,8 @@ export interface WorkflowConfig {
   wrapUpAt: number;
   /** Workers that may run at once when the Master delegates several domains together. */
   maxParallelWorkers: number;
+  /** The oracle starts each task with a clean context: its model is sent only the conversation since the task started, or since the last one ended. */
+  freshContext: boolean;
 }
 
 export interface KnowledgeConfig {
@@ -201,6 +203,7 @@ export const DEFAULT_CONFIG: BotLobbyConfig = {
     toolStallTimeoutMs: 10 * 60 * 1000,
     wrapUpAt: 0.75,
     maxParallelWorkers: 3,
+    freshContext: true,
   },
   knowledge: {
     compactionThreshold: 20000,
@@ -336,6 +339,7 @@ function normalizeClassifier(value: unknown): ClassifierConfig {
 export function resolveConfig(partial: unknown): BotLobbyConfig {
   const src = (partial ?? {}) as Record<string, unknown>;
   const workflow = { ...DEFAULT_CONFIG.workflow, ...(src.workflow as Partial<WorkflowConfig> | undefined) };
+  workflow.freshContext = workflow.freshContext !== false;
   const knowledge = { ...DEFAULT_CONFIG.knowledge, ...(src.knowledge as Partial<KnowledgeConfig> | undefined) };
   const srcAgents = (src.agents ?? {}) as Partial<BotLobbyConfig["agents"]>;
   return {

package/src/state/archive.ts

@@ -6,11 +6,12 @@
  * abandoned before it is archived, so it never comes back half-driven.
  */
 import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { dirname, join, sep } from "node:path";
 import { TERMINAL_STATES, type Task } from "../schemas/task.ts";
 import { taskDir, tasksRoot } from "../knowledge/paths.ts";
 import { transition } from "./task-state.ts";
 import { dataRoot, readDataRoots } from "./project.ts";
+import { forgetCachedUnder, readJsonCached } from "./file-cache.ts";
 
 export function archiveRoot(root: string, configDir: string): string {
   return join(dataRoot(root, configDir), "archive", "tasks");
@@ -43,15 +44,23 @@ function archivedDir(root: string, configDir: string, taskId: string): string {
   return join(archiveRoot(root, configDir), checkId(taskId));
 }
 
-/** Archived tasks, most recently archived first. */
+function isObject(value: unknown): value is Task {
+  return typeof value === "object" && value !== null;
+}
+
+/** Archived tasks, most recently archived first (parsed again only when a file changes; shared, for reading). */
 export function listArchivedTasks(root: string, configDir: string): Task[] {
   const dir = archiveRoot(root, configDir);
   if (!existsSync(dir)) return [];
   const tasks: Task[] = [];
+  const seen = new Set<string>();
   for (const entry of readdirSync(dir)) {
-    const task = readAt(join(dir, entry));
+    const path = join(dir, entry, "state.json");
+    seen.add(path);
+    const task = readJsonCached(path, isObject);
     if (task) tasks.push(task);
   }
+  forgetCachedUnder(`${dir}${sep}`, seen);
   return tasks.sort((a, b) => (b.archivedAt ?? b.updatedAt).localeCompare(a.archivedAt ?? a.updatedAt));
 }
 

package/src/state/backlog.ts

@@ -6,8 +6,9 @@
  * saving at once cannot overwrite each other.
  */
 import { existsSync, readdirSync, readFileSync, rmSync } from "node:fs";
-import { join } from "node:path";
+import { join, sep } from "node:path";
 import { writeFileEnsured } from "../knowledge/store.ts";
+import { forgetCachedUnder, readJsonCached } from "./file-cache.ts";
 import { dataRoot } from "./project.ts";
 import { taskSlug } from "./persistence.ts";
 
@@ -71,16 +72,25 @@ export function loadPlannedTask(root: string, configDir: string, id: string): Pl
   }
 }
 
-/** Every saved entry, pending first, newest first within each group; unreadable files are skipped. */
+/**
+ * Every saved entry, pending first, newest first within each group;
+ * unreadable files are skipped. Files are parsed again only when they change,
+ * and the entries are shared: for reading (the lobby lists them every few
+ * seconds); `loadPlannedTask` gives a copy of one's own.
+ */
 export function listPlannedTasks(root: string, configDir: string): PlannedTask[] {
   const dir = backlogDir(root, configDir);
   if (!existsSync(dir)) return [];
   const entries: PlannedTask[] = [];
+  const seen = new Set<string>();
   for (const file of readdirSync(dir)) {
     if (!file.endsWith(".json")) continue;
-    const entry = loadPlannedTask(root, configDir, file.slice(0, -".json".length));
+    const path = join(dir, file);
+    seen.add(path);
+    const entry = readJsonCached(path, isPlannedTask);
     if (entry) entries.push(entry);
   }
+  forgetCachedUnder(`${dir}${sep}`, seen);
   return entries.sort((a, b) => {
     if (a.status !== b.status) return a.status === "pending" ? -1 : 1;
     return b.updatedAt.localeCompare(a.updatedAt);

package/src/state/file-cache.ts

@@ -0,0 +1,62 @@
+/**
+ * JSON files as last parsed, kept while each file's stat is unchanged. The
+ * owner's clock and the lobby look at every task (and planned or archived
+ * task) every few seconds in every session; a file is parsed again only when
+ * it changed. A file written a moment ago is not kept (two writes that close
+ * together can share a stat), and this process's own writes drop their entry
+ * at once. What comes back is shared with every other caller: for reading
+ * only.
+ */
+import { readFileSync, statSync } from "node:fs";
+
+/** How long ago a file must have been written for its parse to be kept. */
+export const SETTLE_MS = 1000;
+
+/** Files kept at most; the least recently read are let go past this (archived tasks listed once, say). */
+export const CACHE_LIMIT = 512;
+
+const parsed = new Map<string, { stamp: string; value: unknown }>();
+
+/** The file at `path` parsed as JSON and accepted by `valid`; undefined when missing, unreadable or rejected. */
+export function readJsonCached<T>(path: string, valid: (value: unknown) => value is T): T | undefined {
+  let stamp: string;
+  let settled: boolean;
+  try {
+    const stat = statSync(path, { bigint: true });
+    stamp = `${stat.ino}:${stat.size}:${stat.mtimeNs}:${stat.ctimeNs}`;
+    settled = Date.now() - Number(stat.mtimeMs) >= SETTLE_MS;
+  } catch {
+    parsed.delete(path);
+    return undefined;
+  }
+  const hit = parsed.get(path);
+  if (hit?.stamp === stamp) {
+    // Most recently read last, so the one let go is the longest unread.
+    parsed.delete(path);
+    parsed.set(path, hit);
+    return valid(hit.value) ? hit.value : undefined;
+  }
+  let value: unknown;
+  try {
+    value = JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    parsed.delete(path);
+    return undefined;
+  }
+  parsed.delete(path);
+  if (settled) {
+    parsed.set(path, { stamp, value });
+    if (parsed.size > CACHE_LIMIT) parsed.delete(parsed.keys().next().value!);
+  }
+  return valid(value) ? value : undefined;
+}
+
+/** Drop a file's entry (this process is about to write it). */
+export function forgetCached(path: string): void {
+  parsed.delete(path);
+}
+
+/** Drop the entries under `dir` other than `keep` (files that left the folder). */
+export function forgetCachedUnder(dir: string, keep: ReadonlySet<string>): void {
+  for (const path of parsed.keys()) if (path.startsWith(dir) && !keep.has(path)) parsed.delete(path);
+}

package/src/state/metrics.ts

@@ -5,7 +5,7 @@
  * thinking level, how often it succeeds and what it costs. Append-only JSON
  * lines per project; reads keep the newest `MAX_READ` records.
  */
-import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { appendFileSync, closeSync, mkdirSync, openSync, readSync, statSync } from "node:fs";
 import { dirname, join } from "node:path";
 import type { AgentRun } from "../schemas/findings.ts";
 import type { RunLogEntry, Task } from "../schemas/task.ts";
@@ -119,6 +119,20 @@ function isRecord(value: unknown): value is MetricRecord {
   return Boolean(record && typeof record.id === "string" && typeof record.kind === "string" && typeof record.durationMs === "number");
 }
 
+/** How much of a long log's end the first read takes: far more than `MAX_READ` records need. */
+const TAIL_BYTES = 4 * 1024 * 1024;
+
+/** A metrics log as followed so far: the file it was, how far it was read, and its newest records. */
+interface Followed {
+  ino: bigint;
+  offset: number;
+  records: MetricRecord[];
+  /** The first read starts inside the file, part way through a line. */
+  midLine: boolean;
+}
+
+const followed = new Map<string, Followed>();
+
 /** Agent runs for the Metrics tab; classifier calls, a few hundred milliseconds each, are read apart. */
 export function readMetrics(root: string, configDir: string, limit = MAX_READ): MetricRecord[] {
   return readRecords(root, configDir, limit).filter((record) => record.kind !== "classifier");
@@ -129,26 +143,62 @@ export function readClassifierMetrics(root: string, configDir: string, limit = M
   return readRecords(root, configDir, limit).filter((record) => record.kind === "classifier");
 }
 
+/**
+ * The newest records of the project's log, agent runs and classifier calls
+ * alike. The log only grows, so after the first read (of its end only) each
+ * read parses just the lines appended since; a log that shrank or was
+ * replaced is read afresh.
+ */
 function readRecords(root: string, configDir: string, limit: number): MetricRecord[] {
   const path = metricsPath(root, configDir);
-  if (!existsSync(path)) return [];
-  let text: string;
+  let ino: bigint;
+  let size: number;
   try {
-    text = readFileSync(path, "utf8");
+    const stat = statSync(path, { bigint: true });
+    ino = stat.ino;
+    size = Number(stat.size);
   } catch {
+    followed.delete(path);
     return [];
   }
-  const records: MetricRecord[] = [];
-  for (const line of text.split("\n").slice(-limit - 1)) {
-    if (!line.trim()) continue;
-    try {
-      const value = JSON.parse(line) as unknown;
-      if (isRecord(value)) records.push(value);
-    } catch {
-      // Torn lines are skipped.
+  let log = followed.get(path);
+  if (!log || log.ino !== ino || size < log.offset) {
+    const offset = Math.max(0, size - TAIL_BYTES);
+    log = { ino, offset, records: [], midLine: offset > 0 };
+    followed.set(path, log);
+  }
+  if (size > log.offset) readAppended(path, log, size);
+  return log.records.length > limit ? log.records.slice(-limit) : [...log.records];
+}
+
+function readAppended(path: string, log: Followed, size: number): void {
+  let fd: number | undefined;
+  try {
+    fd = openSync(path, "r");
+    const buffer = Buffer.alloc(size - log.offset);
+    const read = readSync(fd, buffer, 0, buffer.length, log.offset);
+    // Whole lines only: one still being appended is read next time.
+    const end = buffer.lastIndexOf(0x0a, read - 1);
+    if (end < 0) return;
+    const lines = buffer.toString("utf8", 0, end).split("\n");
+    if (log.midLine) lines.shift();
+    log.midLine = false;
+    for (const line of lines) {
+      if (!line.trim()) continue;
+      try {
+        const value = JSON.parse(line) as unknown;
+        if (isRecord(value)) log.records.push(value);
+      } catch {
+        // Torn lines are skipped.
+      }
     }
+    if (log.records.length > MAX_READ) log.records.splice(0, log.records.length - MAX_READ);
+    log.offset += end + 1;
+  } catch {
+    // Unreadable for now; the next read tries again.
+  } finally {
+    if (fd !== undefined) closeSync(fd);
   }
-  return records.slice(-limit);
 }
 
 const AGENT_NAMES: Record<string, string> = { backend: "DEV", designer: "DESIGN", qa: "QA" };

package/src/state/persistence.ts

@@ -1,5 +1,5 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync } from "node:fs";
-import { join } from "node:path";
+import { join, sep } from "node:path";
 import type { KnowledgeConfig } from "../schemas/configuration.ts";
 import type { Domain } from "../schemas/agent.ts";
 import { TERMINAL_STATES, isTaskState, type Task } from "../schemas/task.ts";
@@ -14,6 +14,7 @@ import {
   type KnowledgeAgent,
 } from "../knowledge/paths.ts";
 import { DEFAULT_KNOWLEDGE_CONTENT, ensureFile, readFileOr, writeFileEnsured } from "../knowledge/store.ts";
+import { forgetCached, forgetCachedUnder, readJsonCached } from "./file-cache.ts";
 
 /** Idempotently create the full knowledge + tasks layout with seed files. */
 export function ensureProjectStructure(root: string, configDir: string): void {
@@ -36,6 +37,7 @@ export function ensureProjectStructure(root: string, configDir: string): void {
 export function createTaskDir(root: string, configDir: string, task: Task): void {
   const dir = taskDir(dataRoot(root, configDir), task.id);
   mkdirSync(dir, { recursive: true });
+  forgetCached(join(dir, "state.json"));
   writeFileEnsured(join(dir, "state.json"), JSON.stringify(task, null, 2));
   ensureFile(join(dir, "proposal.md"), "");
   ensureFile(join(dir, "plan.md"), "");
@@ -77,7 +79,9 @@ export function readTaskArtifact(
 }
 
 export function saveTask(root: string, configDir: string, task: Task): void {
-  writeFileEnsured(join(taskDir(dataRoot(root, configDir), task.id), "state.json"), JSON.stringify(task, null, 2));
+  const path = join(taskDir(dataRoot(root, configDir), task.id), "state.json");
+  forgetCached(path);
+  writeFileEnsured(path, JSON.stringify(task, null, 2));
 }
 
 /** Read a task state: the bot-lobby copy wins, else the newest pre-rename copy. */
@@ -147,6 +151,36 @@ export function listTasks(root: string, configDir: string): Task[] {
   return tasks.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
 }
 
+/** Any parsed JSON object counts as a task, as `readTaskAt` has it. */
+function isObject(value: unknown): value is Task {
+  return typeof value === "object" && value !== null;
+}
+
+/**
+ * All tasks on disk, newest first, like `listTasks`, but a file is read only
+ * when it changed since the last look. The tasks are shared with every other
+ * caller, so they are for reading (the owner's clock, the lobby): whatever
+ * changes a task loads its own copy with `loadTask` and saves that.
+ */
+export function peekTasks(root: string, configDir: string): Task[] {
+  const tasks: Task[] = [];
+  const seen = new Set<string>();
+  for (const { dir } of taskEntries(root, configDir)) {
+    const path = join(dir, "state.json");
+    seen.add(path);
+    const task = readJsonCached(path, isObject);
+    if (task) tasks.push(task);
+  }
+  // Forget tasks that left these folders (deleted or archived).
+  for (const dr of readDataRoots(root, configDir)) forgetCachedUnder(`${tasksRoot(dr)}${sep}`, seen);
+  return tasks.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+}
+
+/** The non-terminal task a session owns, from `peekTasks` (for reading only). */
+export function peekOwnedTask(root: string, configDir: string, sessionId: string): Task | undefined {
+  return peekTasks(root, configDir).find((task) => !TERMINAL_STATES.includes(task.state) && task.ownerSessionId === sessionId);
+}
+
 /** Tasks on disk plus the ids whose state.json could not be read (§59). */
 export function taskHealth(root: string, configDir: string): { tasks: Task[]; corrupted: string[] } {
   const tasks: Task[] = [];

package/src/width.ts

@@ -0,0 +1,102 @@
+/**
+ * Terminal width of styled text, fast. pi-tui's `visibleWidth` segments every
+ * string into grapheme clusters, which is exact but slow, and its cache only
+ * helps strings seen before: the lobby's rows are new strings every frame
+ * (boxes side by side, a clock, a spinner). This scans them instead: ASCII
+ * counts one column, escape sequences none, and every other character in the
+ * ranges below is measured once with pi-tui (on its own, as the cluster it
+ * always is there) and remembered. Anything else — combining marks, variation
+ * selectors, joiners, emoji or CJK outside those ranges — goes to pi-tui for
+ * the whole string, so the answer is always pi-tui's.
+ */
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+
+/** Characters that always stand alone as a cluster: Latin, punctuation, arrows, symbols, box drawing, shapes, braille. */
+function standsAlone(code: number): boolean {
+  return (code >= 0xa0 && code < 0x300 && code !== 0xad)
+    || (code >= 0x2010 && code <= 0x2027)
+    || (code >= 0x2030 && code <= 0x205e)
+    || (code >= 0x2190 && code <= 0x23ff)
+    || (code >= 0x2500 && code <= 0x27bf)
+    || (code >= 0x2800 && code <= 0x29ff);
+}
+
+/**
+ * The length of the escape sequence at `index` that takes no columns, exactly
+ * as pi-tui reads them — CSI ending in m, G, K, H or J (parameters only
+ * before it), OSC and APC ending in BEL or ST — or 0 for any other.
+ */
+function escapeLength(text: string, index: number): number {
+  const kind = text.charCodeAt(index + 1);
+  if (kind === 0x5b) {
+    for (let at = index + 2; at < text.length; at += 1) {
+      const code = text.charCodeAt(at);
+      // m G K H J end it; digits, ; : ? are its parameters; anything else is read differently by pi-tui.
+      if (code === 0x6d || code === 0x47 || code === 0x4b || code === 0x48 || code === 0x4a) return at + 1 - index;
+      if (!((code >= 0x30 && code <= 0x3b) || code === 0x3f)) return 0;
+    }
+    return 0;
+  }
+  if (kind === 0x5d || kind === 0x5f) {
+    for (let at = index + 2; at < text.length; at += 1) {
+      const code = text.charCodeAt(at);
+      if (code === 0x07) return at + 1 - index;
+      if (code === 0x1b) return text.charCodeAt(at + 1) === 0x5c ? at + 2 - index : 0;
+    }
+  }
+  return 0;
+}
+
+const charWidths = new Map<number, number>();
+
+function scan(text: string): number {
+  let width = 0;
+  for (let index = 0; index < text.length; ) {
+    const code = text.charCodeAt(index);
+    if (code >= 0x20 && code < 0x7f) {
+      width += 1;
+      index += 1;
+    } else if (code === 0x1b) {
+      const length = escapeLength(text, index);
+      if (length === 0) return visibleWidth(text);
+      index += length;
+    } else {
+      if (!standsAlone(code)) return visibleWidth(text);
+      let columns = charWidths.get(code);
+      if (columns === undefined) {
+        columns = visibleWidth(String.fromCharCode(code));
+        charWidths.set(code, columns);
+      }
+      width += columns;
+      index += 1;
+    }
+  }
+  return width;
+}
+
+/** Widths of recent strings: a frame mostly repeats the last one's lines (a few hundred of them). */
+const recent = new Map<string, number>();
+const RECENT_LIMIT = 1024;
+
+/** Columns `text` takes in a terminal; the same as pi-tui's `visibleWidth`. */
+export function textWidth(text: string): number {
+  if (text.length < 16) return scan(text);
+  const known = recent.get(text);
+  if (known !== undefined) return known;
+  const width = scan(text);
+  if (recent.size >= RECENT_LIMIT) recent.delete(recent.keys().next().value!);
+  recent.set(text, width);
+  return width;
+}
+
+/**
+ * `text` cut to `width` columns (ending in `ellipsis`), padded to it when
+ * `pad`: pi-tui's `truncateToWidth`, which walks every character even when
+ * the text already fits — checked first here, since most lines do.
+ */
+export function clip(text: string, width: number, ellipsis = "...", pad = false): string {
+  if (width <= 0) return "";
+  const columns = textWidth(text);
+  if (columns <= width) return pad && columns < width ? `${text}${" ".repeat(width - columns)}` : text;
+  return truncateToWidth(text, width, ellipsis, pad);
+}