@a-t-h-i/bot-lobby 0.6.36 → 0.6.38

package/src/scripts/library.ts

@@ -0,0 +1,168 @@
+/**
+ * The scripts library: scripts every agent shares for jobs that come back
+ * (seeding data, regenerating fixtures, a set of checks, a migration), so a
+ * step done once is run the next time, not worked out again, which saves
+ * tokens and time. They live in `<data>/scripts/`, one file each, named for
+ * what they do in snake_case with the language's extension
+ * (`seed_public_holidays.py`, `run_changed_tests.sh`). The first lines of each
+ * file say what it is for and how to run it, and the library's index is read
+ * from them, so a script edited by hand stays listed. Only the oracle adds or
+ * replaces a script; workers propose one. A replaced script is kept under
+ * `archive/`.
+ */
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+/** The languages a script may be written in: how it is run and how its header lines are commented. */
+export const SCRIPT_LANGUAGES = {
+  py: { runner: "python3", comment: "#" },
+  sh: { runner: "bash", comment: "#" },
+  bash: { runner: "bash", comment: "#" },
+  js: { runner: "node", comment: "//" },
+  mjs: { runner: "node", comment: "//" },
+  cjs: { runner: "node", comment: "//" },
+  ts: { runner: "node", comment: "//" },
+  rb: { runner: "ruby", comment: "#" },
+  pl: { runner: "perl", comment: "#" },
+  ps1: { runner: "pwsh -File", comment: "#" },
+} as const;
+export type ScriptLanguage = keyof typeof SCRIPT_LANGUAGES;
+
+/** Longest name, extension included. */
+export const MAX_SCRIPT_NAME = 64;
+/** Largest script the library takes. */
+export const MAX_SCRIPT_BYTES = 64 * 1024;
+
+const NAME = new RegExp(`^[a-z][a-z0-9]*(?:_[a-z0-9]+)+\\.(${Object.keys(SCRIPT_LANGUAGES).join("|")})$`);
+/** How many lines from the top the header is looked for in. */
+const HEADER_LINES = 12;
+
+export interface ScriptEntry {
+  /** The file name: `seed_public_holidays.py`. */
+  name: string;
+  path: string;
+  language: ScriptLanguage;
+  /** What it is for, one line. */
+  purpose: string;
+  /** How to run it, with its arguments; the runner and path when the header gives none. */
+  usage: string;
+}
+
+export function scriptsDir(dataRoot: string): string {
+  return join(dataRoot, "scripts");
+}
+
+/** The words of a name (`seed_public_holidays.py` → `seed public holidays`), for matching it against a step. */
+export function nameWords(name: string): string {
+  return name.replace(/\.[a-z0-9]+$/, "").replace(/_/g, " ");
+}
+
+/**
+ * The library name for what was asked: lower-cased, spaces and hyphens as
+ * underscores (`Seed public-holidays.py` → `seed_public_holidays.py`). Throws
+ * with what is wrong when it still does not read `<what_it_does>.<ext>`.
+ */
+export function scriptName(asked: string): string {
+  const name = asked.trim().toLowerCase().replace(/[\s-]+/g, "_").replace(/_+/g, "_");
+  const languages = Object.keys(SCRIPT_LANGUAGES).map((ext) => `.${ext}`).join(", ");
+  if (!/\.[a-z0-9]+$/.test(name) || !(name.split(".").pop()! in SCRIPT_LANGUAGES)) {
+    throw new Error(`a script name ends in its language's extension (${languages}): "${asked}"`);
+  }
+  if (name.length > MAX_SCRIPT_NAME) throw new Error(`a script name is at most ${MAX_SCRIPT_NAME} characters: "${asked}"`);
+  if (!NAME.test(name)) {
+    throw new Error(`a script is named for what it does, in snake_case words (seed_public_holidays.py): "${asked}"`);
+  }
+  return name;
+}
+
+function language(name: string): ScriptLanguage {
+  return name.split(".").pop() as ScriptLanguage;
+}
+
+function headerValue(lines: readonly string[], key: string): string | undefined {
+  const line = lines.find((entry) => new RegExp(`^\\s*(?:#|//)\\s*${key}\\s*:`, "i").test(entry));
+  return line?.replace(new RegExp(`^\\s*(?:#|//)\\s*${key}\\s*:\\s*`, "i"), "").trim() || undefined;
+}
+
+/** The command that runs a script when its header gives none. */
+export function runCommand(entry: Pick<ScriptEntry, "path" | "language">): string {
+  return `${SCRIPT_LANGUAGES[entry.language].runner} ${entry.path}`;
+}
+
+function readEntry(dir: string, name: string): ScriptEntry | undefined {
+  const path = join(dir, name);
+  try {
+    if (!statSync(path).isFile()) return undefined;
+    const lines = readFileSync(path, "utf8").split("\n").slice(0, HEADER_LINES);
+    const entry = { name, path, language: language(name) };
+    return { ...entry, purpose: headerValue(lines, "purpose") ?? nameWords(name), usage: headerValue(lines, "usage") ?? runCommand(entry) };
+  } catch {
+    return undefined;
+  }
+}
+
+/** Every script in the library, by name; files not named like a script are left out. */
+export function listScripts(dataRoot: string): ScriptEntry[] {
+  const dir = scriptsDir(dataRoot);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((name) => NAME.test(name))
+    .sort()
+    .map((name) => readEntry(dir, name))
+    .filter((entry): entry is ScriptEntry => entry !== undefined);
+}
+
+/** The body with any header lines of its own taken out, and a shebang it starts with kept apart. */
+function splitBody(body: string): { shebang?: string; rest: string } {
+  const lines = body.replace(/\r\n/g, "\n").split("\n");
+  const shebang = lines[0]?.startsWith("#!") ? lines.shift() : undefined;
+  const rest = lines.filter((line, index) => index >= HEADER_LINES || !/^\s*(?:#|\/\/)\s*(?:purpose|usage)\s*:/i.test(line));
+  while (rest.length > 0 && rest[0]!.trim() === "") rest.shift();
+  return { ...(shebang ? { shebang } : {}), rest: rest.join("\n") };
+}
+
+export interface SaveScript {
+  dataRoot: string;
+  name: string;
+  purpose: string;
+  /** How to run it, with its arguments; the runner and path when absent. */
+  usage?: string;
+  body: string;
+}
+
+export interface SavedScript {
+  entry: ScriptEntry;
+  /** Where the version it replaced was kept, when there was one. */
+  archived?: string;
+}
+
+/**
+ * Add a script to the library, or replace the one of that name (the old one
+ * is kept under `archive/`). The engine writes its header: purpose and usage
+ * as comments after any shebang, so the index never depends on the agent
+ * having written one.
+ */
+export function saveScript(input: SaveScript, now = new Date()): SavedScript {
+  const name = scriptName(input.name);
+  const purpose = input.purpose.replace(/\s+/g, " ").trim();
+  if (!purpose) throw new Error("a script needs its purpose: one line on what it does");
+  const { shebang, rest } = splitBody(input.body);
+  if (!rest.trim()) throw new Error("the script is empty");
+  const dir = scriptsDir(input.dataRoot);
+  const path = join(dir, name);
+  const lang = language(name);
+  const usage = input.usage?.replace(/\s+/g, " ").trim() || runCommand({ path, language: lang });
+  const { comment } = SCRIPT_LANGUAGES[lang];
+  const text = [...(shebang ? [shebang] : []), `${comment} purpose: ${purpose}`, `${comment} usage: ${usage}`, "", rest.replace(/\s+$/, ""), ""].join("\n");
+  if (Buffer.byteLength(text) > MAX_SCRIPT_BYTES) throw new Error(`a script is at most ${MAX_SCRIPT_BYTES / 1024} KB`);
+  mkdirSync(dir, { recursive: true });
+  let archived: string | undefined;
+  if (existsSync(path)) {
+    if (readFileSync(path, "utf8") === text) return { entry: readEntry(dir, name)! };
+    mkdirSync(join(dir, "archive"), { recursive: true });
+    archived = join(dir, "archive", `${name}.${now.toISOString().replace(/[:.]/g, "-")}`);
+    copyFileSync(path, archived);
+  }
+  writeFileSync(path, text, { mode: 0o755 });
+  return { entry: readEntry(dir, name)!, ...(archived ? { archived } : {}) };
+}

package/src/scripts/pick.ts

@@ -0,0 +1,79 @@
+/**
+ * Which of the library's scripts fit a step, and how an agent's prompt shows
+ * them. Jev judges each script against the step when it is on (see
+ * `classifier/scripts.ts`); without it, or when it fails, a script fits when
+ * its name or purpose shares words with the step. Either way the prompt names
+ * the library, so an agent can look for itself.
+ */
+import { score, tokenize } from "../knowledge/selector.ts";
+import { listScripts, nameWords, scriptsDir, type ScriptEntry } from "./library.ts";
+
+/** Most scripts one prompt suggests. */
+export const MAX_SUGGESTED = 6;
+/** Most scripts the oracle's prompt lists. */
+export const MAX_LISTED = 40;
+
+/** The scripts whose name or purpose shares the most words with the step, best first. */
+export function keywordScripts(step: string, entries: readonly ScriptEntry[], limit = MAX_SUGGESTED): ScriptEntry[] {
+  const tokens = tokenize(step);
+  return entries
+    .map((entry, index) => ({ entry, index, hits: score(`${nameWords(entry.name)} ${entry.purpose}`, tokens) }))
+    .filter((scored) => scored.hits > 0)
+    .sort((a, b) => b.hits - a.hits || a.index - b.index)
+    .slice(0, limit)
+    .map((scored) => scored.entry);
+}
+
+/** Picks the scripts that fit a step. */
+export interface ScriptPicker {
+  pick(step: string, entries: readonly ScriptEntry[], options?: { signal?: AbortSignal }): Promise<ScriptEntry[]>;
+}
+
+/** The picker that goes by shared words alone. */
+export const keywordPicker: ScriptPicker = { pick: async (step, entries) => keywordScripts(step, entries) };
+
+function line(entry: ScriptEntry): string {
+  return `- \`${entry.name}\` — ${entry.purpose}\n  run: \`${entry.usage}\``;
+}
+
+/**
+ * The Scripts layer of a worker's, scout's or QA agent's prompt: the scripts
+ * that fit this step and how to run each, then where the rest are. "" while
+ * the library is empty.
+ */
+export function scriptsBlock(dataRoot: string, entries: readonly ScriptEntry[], picked: readonly ScriptEntry[]): string {
+  if (entries.length === 0) return "";
+  const where = `The shared scripts library (${entries.length} script${entries.length === 1 ? "" : "s"}) is \`${scriptsDir(dataRoot)}\`; each file's first lines say what it does and how to run it.`;
+  if (picked.length === 0) return `None of the shared scripts fits this step. ${where}`;
+  return [
+    "These shared scripts do part of this step: run one instead of doing its work by hand, and check its output as you would your own.",
+    ...picked.map(line),
+    where,
+  ].join("\n");
+}
+
+/** The oracle's view of the library: every script by name and purpose, so it can point a brief at one. */
+export function libraryBlock(dataRoot: string, entries: readonly ScriptEntry[] = listScripts(dataRoot)): string {
+  const dir = scriptsDir(dataRoot);
+  if (entries.length === 0) return `The shared scripts library (\`${dir}\`) is empty.`;
+  const shown = entries.slice(0, MAX_LISTED).map((entry) => `- \`${entry.name}\` — ${entry.purpose}`);
+  const more = entries.length > MAX_LISTED ? [`…and ${entries.length - MAX_LISTED} more in \`${dir}\`.`] : [];
+  return [`Shared scripts (\`${dir}\`):`, ...shown, ...more].join("\n");
+}
+
+/**
+ * The Scripts layer for one agent's step: the library read, the picker's
+ * choice (shared words when it fails), and the block. "" with no scripts.
+ */
+export async function scriptsFor(dataRoot: string | undefined, step: string, picker: ScriptPicker = keywordPicker, signal?: AbortSignal): Promise<string> {
+  if (!dataRoot) return "";
+  const entries = listScripts(dataRoot);
+  if (entries.length === 0) return "";
+  let picked: ScriptEntry[];
+  try {
+    picked = await picker.pick(step, entries, signal ? { signal } : {});
+  } catch {
+    picked = keywordScripts(step, entries);
+  }
+  return scriptsBlock(dataRoot, entries, picked.slice(0, MAX_SUGGESTED));
+}

package/src/state/step-limits.ts

@@ -0,0 +1,41 @@
+import { readWork, updateWork } from "./work-time.ts";
+
+export const STEP_LIMIT_MS = 15 * 60_000;
+
+export function stepTimeLeft(root: string, configDir: string, taskId: string, keys: readonly string[], limitMs: number): number {
+  const limits = readWork(root, configDir, taskId, true)?.stepLimits;
+  return Math.max(0, Math.min(limitMs, ...keys.map((key) => {
+    const entry = limits?.[key];
+    if (!entry) return limitMs;
+    if (!Number.isFinite(entry.limitMs) || !Number.isFinite(entry.usedMs) || entry.limitMs < 0 || entry.usedMs < 0) throw new Error("Invalid step allowance");
+    return entry.limitMs - entry.usedMs;
+  })));
+}
+
+/** Reserve before starting: a crash must not silently give the step a fresh allowance. */
+export function reserveStepTime(root: string, configDir: string, taskId: string, keys: readonly string[], limitMs: number, ms: number) {
+  let reserved = ms;
+  const change = (fn: (entry: { limitMs: number; usedMs: number }) => void) => updateWork(root, configDir, taskId, (work) => {
+    work.stepLimits ??= {};
+    for (const key of keys) fn(work.stepLimits[key] ??= { limitMs, usedMs: 0 });
+  }, new Date(), true);
+  if (!(ms > 0) || ms > stepTimeLeft(root, configDir, taskId, keys, limitMs)) throw new Error("The step has no time left");
+  change((entry) => { entry.usedMs += ms; });
+  return {
+    grant(extraMs: number) {
+      change((entry) => { entry.limitMs += extraMs; entry.usedMs += extraMs; });
+      reserved += extraMs;
+    },
+    finish(usedMs: number, exhausted = false) {
+      const refund = exhausted ? 0 : Math.max(0, reserved - usedMs);
+      change((entry) => { entry.usedMs = Math.max(0, entry.usedMs - refund); });
+    },
+  };
+}
+
+export function grantStepTime(root: string, configDir: string, taskId: string, keys: readonly string[], limitMs: number, extraMs: number): void {
+  updateWork(root, configDir, taskId, (work) => {
+    work.stepLimits ??= {};
+    for (const key of keys) (work.stepLimits[key] ??= { limitMs, usedMs: 0 }).limitMs += extraMs;
+  }, new Date(), true);
+}

package/src/state/work-time.ts

@@ -29,6 +29,7 @@ export interface WorkTime {
   active: ActiveRun[];
   /** When the owning session last wrote it. */
   updatedAt: string;
+  stepLimits?: Record<string, { limitMs: number; usedMs: number }>;
 }
 
 /** The clock as a reader sees it at one moment. */
@@ -48,32 +49,36 @@ export function workPath(root: string, configDir: string, taskId: string): strin
 
 function isWork(value: unknown): value is WorkTime {
   const work = value as Partial<WorkTime> | undefined;
-  return Boolean(work && typeof work.workedMs === "number" && typeof work.updatedAt === "string");
+  return Boolean(work && Number.isFinite(work.workedMs) && typeof work.updatedAt === "string"
+    && (work.stepLimits === undefined || (work.stepLimits !== null && typeof work.stepLimits === "object" && !Array.isArray(work.stepLimits)
+      && Object.values(work.stepLimits).every((entry) => entry && Number.isFinite(entry.limitMs) && Number.isFinite(entry.usedMs) && entry.limitMs >= 0 && entry.usedMs >= 0))));
 }
 
-export function readWork(root: string, configDir: string, taskId: string): WorkTime | undefined {
+export function readWork(root: string, configDir: string, taskId: string, strict = false): WorkTime | undefined {
   try {
     const value: unknown = JSON.parse(readFileSync(workPath(root, configDir, taskId), "utf8"));
-    if (!isWork(value)) return undefined;
-    return { workedMs: value.workedMs, ...(value.runningSince ? { runningSince: value.runningSince } : {}), active: Array.isArray(value.active) ? value.active : [], updatedAt: value.updatedAt };
-  } catch {
+    if (!isWork(value)) throw new Error("Invalid task work record");
+    return { workedMs: value.workedMs, ...(value.runningSince ? { runningSince: value.runningSince } : {}), active: Array.isArray(value.active) ? value.active : [], updatedAt: value.updatedAt, ...(value.stepLimits ? { stepLimits: value.stepLimits } : {}) };
+  } catch (error) {
+    if (strict && (error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
     return undefined;
   }
 }
 
 /** Change a task's work time in place (read afresh, written back atomically), starting it when there is none. */
-export function updateWork(root: string, configDir: string, taskId: string, change: (work: WorkTime) => void, now = new Date()): void {
-  const work = readWork(root, configDir, taskId) ?? { workedMs: 0, active: [], updatedAt: now.toISOString() };
-  change(work);
-  work.updatedAt = now.toISOString();
+export function updateWork(root: string, configDir: string, taskId: string, change: (work: WorkTime) => void, now = new Date(), strict = false): void {
   try {
+    const work = readWork(root, configDir, taskId, true) ?? { workedMs: 0, active: [], updatedAt: now.toISOString() };
+    change(work);
+    work.updatedAt = now.toISOString();
     const path = workPath(root, configDir, taskId);
     mkdirSync(dirname(path), { recursive: true });
     const tmp = `${path}.${process.pid}.tmp`;
     writeFileSync(tmp, `${JSON.stringify(work, null, 2)}\n`, "utf8");
     renameSync(tmp, path);
-  } catch {
-    // A read-only tree must never fail the workflow; the time just stops being saved.
+  } catch (error) {
+    if (strict) throw error;
+    // Display clocks may stop; never overwrite an unreadable allowance ledger.
   }
 }
 

package/src/webui/api/lobby.ts

@@ -24,7 +24,7 @@ function planFacts(task: Task, work: WorkProjection | undefined): Pick<SnapshotT
   return {
     progress: { done: steps.filter((step) => step.status === "done").length, total: steps.length },
     ...(current ? { currentStep: current.text } : {}),
-    ...(active.length > 0 ? { activeSteps: active.map((step) => ({ text: step.text, workedMs: step.workedMs, activeAgentCount: step.activeAgentCount })) } : {}),
+    ...(active.length > 0 ? { activeSteps: active.map((step) => ({ text: step.text, workedMs: step.workedMs, activeAgentCount: step.activeAgentCount, runIds: step.runIds })) } : {}),
     ...clock,
   };
 }

package/src/webui/api/plan-facts.ts

@@ -39,6 +39,7 @@ export interface StepView {
   status: PlanStep["status"];
   active: boolean;
   activeAgentCount: number;
+  runIds: string[];
   /** Worker time on the step, in ms. */
   workedMs: number;
 }
@@ -54,7 +55,7 @@ export function stepViews(task: Task, work: WorkProjection | undefined, now = Da
   const checklist = planChecklist(task.plan, runs);
   const times = stepWork(planSteps(task.plan), runs, now);
   return checklist.map((step, index) => {
-    const time = times[index] ?? { ms: 0, active: false, activeAgentCount: 0 };
-    return { text: step.text, status: time.active ? "current" : step.status, active: time.active, activeAgentCount: time.activeAgentCount, workedMs: Math.round(time.ms) };
+    const time = times[index] ?? { ms: 0, active: false, activeAgentCount: 0, runIds: [] };
+    return { text: step.text, status: time.active ? "current" : step.status, active: time.active, activeAgentCount: time.activeAgentCount, runIds: time.runIds, workedMs: Math.round(time.ms) };
   });
 }

package/src/webui/protocol.ts

@@ -131,7 +131,7 @@ export interface SnapshotTask {
   progress?: { done: number; total: number };
   currentStep?: string;
   /** The steps a worker is on right now, with the worker time on each (ms, as of the snapshot). */
-  activeSteps?: Array<{ text: string; workedMs: number; activeAgentCount?: number }>;
+  activeSteps?: Array<{ text: string; workedMs: number; activeAgentCount?: number; runIds?: string[] }>;
   /** How long the task's agents have worked on it, idle time left out. */
   work?: WorkClock;
 }