@a-t-h-i/bot-lobby 0.1.0

package/src/state/persistence.ts

@@ -0,0 +1,232 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import { join } 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";
+import { dataRoot, firstLegacyDataRoot, readDataRoots } from "./project.ts";
+import {
+  AGENT_DIR_NAMES,
+  KNOWLEDGE_FILES,
+  knowledgeDir,
+  scratchpadPath,
+  taskDir,
+  tasksRoot,
+  type KnowledgeAgent,
+} from "../knowledge/paths.ts";
+import { DEFAULT_KNOWLEDGE_CONTENT, ensureFile, readFileOr, writeFileEnsured } from "../knowledge/store.ts";
+
+/** Idempotently create the full knowledge + tasks layout with seed files. */
+export function ensureProjectStructure(root: string, configDir: string): void {
+  const dr = dataRoot(root, configDir);
+  const legacy = firstLegacyDataRoot(root, configDir);
+  const agents = Object.keys(AGENT_DIR_NAMES) as KnowledgeAgent[];
+  for (const agent of agents) {
+    const dir = knowledgeDir(dr, agent);
+    mkdirSync(dir, { recursive: true });
+    for (const file of KNOWLEDGE_FILES[agent]) {
+      // Seed from the newest existing pre-rename tree so legacy knowledge migrates instead of being shadowed by defaults.
+      const migrated = legacy ? readFileOr(join(knowledgeDir(legacy, agent), file)) : "";
+      ensureFile(join(dir, file), migrated || (DEFAULT_KNOWLEDGE_CONTENT[file] ?? `# ${file}\n`));
+    }
+  }
+  mkdirSync(tasksRoot(dr), { recursive: true });
+}
+
+/** Create the temporary task dir with state.json, proposal/plan, scratchpads. */
+export function createTaskDir(root: string, configDir: string, task: Task): void {
+  const dir = taskDir(dataRoot(root, configDir), task.id);
+  mkdirSync(dir, { recursive: true });
+  writeFileEnsured(join(dir, "state.json"), JSON.stringify(task, null, 2));
+  ensureFile(join(dir, "proposal.md"), "");
+  ensureFile(join(dir, "plan.md"), "");
+  for (const domain of ["designer", "backend", "qa"] as const) {
+    ensureFile(scratchpadPath(dir, domain), `# ${domain} scratchpad\n`);
+  }
+}
+
+export function taskDirFor(root: string, configDir: string, taskId: string): string {
+  return taskDir(dataRoot(root, configDir), taskId);
+}
+
+/** Per-task dirs to read, newest first: bot-lobby, then the pre-rename trees. */
+export function taskReadDirs(root: string, configDir: string, taskId: string): string[] {
+  return readDataRoots(root, configDir).map((dr) => taskDir(dr, taskId));
+}
+
+function readIfExists(path: string): string | undefined {
+  if (!existsSync(path)) return undefined;
+  try {
+    return readFileSync(path, "utf8");
+  } catch {
+    return undefined;
+  }
+}
+
+/** Read the first existing per-task artifact; the new tree wins per file. */
+export function readTaskArtifact(
+  root: string,
+  configDir: string,
+  taskId: string,
+  relative: string,
+): string | undefined {
+  for (const dir of taskReadDirs(root, configDir, taskId)) {
+    const text = readIfExists(join(dir, relative));
+    if (text !== undefined) return text;
+  }
+  return undefined;
+}
+
+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));
+}
+
+/** Read a task state: the bot-lobby copy wins, else the newest pre-rename copy. */
+export function loadTask(root: string, configDir: string, taskId: string): Task | undefined {
+  for (const dr of readDataRoots(root, configDir)) {
+    const path = join(taskDir(dr, taskId), "state.json");
+    if (!existsSync(path)) continue;
+    try {
+      return JSON.parse(readFileSync(path, "utf8")) as Task;
+    } catch {
+      // A bot-lobby state.json that exists but cannot be parsed is surfaced, not shadowed.
+      return undefined;
+    }
+  }
+  return undefined;
+}
+
+/** Enforce the scratchpad size cap (§20) before writing. */
+export function capScratchpad(content: string, cfg: KnowledgeConfig): string {
+  const paragraphs = content.split(/\n\s*\n/).filter((p) => p.trim().length > 0);
+  const limited = paragraphs.slice(0, cfg.scratchpadMaxParagraphs).join("\n\n");
+  if (limited.length <= cfg.scratchpadMaxChars) return limited;
+  return `${limited.slice(0, cfg.scratchpadMaxChars)}\n\n[truncated]`;
+}
+
+export function writeScratchpad(dir: string, domain: Domain, content: string, cfg: KnowledgeConfig): void {
+  writeFileEnsured(scratchpadPath(dir, domain), capScratchpad(content, cfg));
+}
+
+/** Read one task dir's state.json; missing and unreadable both yield undefined. */
+function readTaskAt(dir: string): Task | undefined {
+  const path = join(dir, "state.json");
+  if (!existsSync(path)) return undefined;
+  try {
+    return JSON.parse(readFileSync(path, "utf8")) as Task;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Task dirs across the merged read roots, bot-lobby first and winning per
+ * entry, so a legacy task stays visible until its id exists in the new tree.
+ */
+function taskEntries(root: string, configDir: string): { entry: string; dir: string }[] {
+  const entries: { entry: string; dir: string }[] = [];
+  const seen = new Set<string>();
+  for (const dr of readDataRoots(root, configDir)) {
+    const dir = tasksRoot(dr);
+    if (!existsSync(dir)) continue;
+    for (const entry of readdirSync(dir)) {
+      if (seen.has(entry)) continue;
+      seen.add(entry);
+      entries.push({ entry, dir: join(dir, entry) });
+    }
+  }
+  return entries;
+}
+
+/** All tasks on disk, newest first. Unreadable task dirs are skipped. */
+export function listTasks(root: string, configDir: string): Task[] {
+  const tasks: Task[] = [];
+  for (const { entry, dir } of taskEntries(root, configDir)) {
+    const task = readTaskAt(dir);
+    if (task) tasks.push(task);
+  }
+  return tasks.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+}
+
+/** 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[] = [];
+  const corrupted: string[] = [];
+  for (const { entry, dir } of taskEntries(root, configDir)) {
+    const task = readTaskAt(dir);
+    if (!task || task.id !== entry || !isTaskState(task.state)) corrupted.push(entry);
+    else tasks.push(task);
+  }
+  return { tasks: tasks.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt)), corrupted };
+}
+
+/** The task the Master is currently driving, if any. */
+export function activeTask(root: string, configDir: string, sessionId?: string): Task | undefined {
+  if (sessionId !== undefined) return ownedTask(root, configDir, sessionId);
+  return listTasks(root, configDir).find((task) => !TERMINAL_STATES.includes(task.state));
+}
+
+/** The non-terminal task a session owns, if any. */
+export function ownedTask(root: string, configDir: string, sessionId: string): Task | undefined {
+  return listTasks(root, configDir).find((task) => !TERMINAL_STATES.includes(task.state) && task.ownerSessionId === sessionId);
+}
+
+/** The newest non-terminal task with no owner, if any. */
+export function ownerlessTask(root: string, configDir: string): Task | undefined {
+  return listTasks(root, configDir).find((task) => !TERMINAL_STATES.includes(task.state) && !task.ownerSessionId);
+}
+
+/** A specific task, or the session's active one when no id is given. */
+export function selectTask(root: string, configDir: string, taskId?: string, sessionId?: string): Task | undefined {
+  return taskId ? loadTask(root, configDir, taskId) : activeTask(root, configDir, sessionId);
+}
+
+/** Reassign a task to a session; explicit takeover for orphaned tasks. */
+export function claimTask(root: string, configDir: string, taskId: string, sessionId: string): Task | undefined {
+  const task = loadTask(root, configDir, taskId);
+  if (!task) return undefined;
+  task.ownerSessionId = sessionId;
+  task.updatedAt = new Date().toISOString();
+  saveTask(root, configDir, task);
+  return task;
+}
+
+/** Dash-slug of a request: lowercase, non-alphanumerics collapsed, capped at `max`. */
+export function taskSlug(request: string, max = 40): string {
+  return request
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, max)
+    .replace(/-+$/, "");
+}
+
+/**
+ * Task id from the request (`TASK-<slug>`); requests with no usable slug fall
+ * back to the timestamped `TASK-task-<timestamp>` form callers already suffix.
+ */
+export function nextTaskId(request: string, now = new Date()): string {
+  const slug = taskSlug(request);
+  if (slug.length > 0) return `TASK-${slug}`;
+  return `TASK-task-${now.toISOString().replace(/[-:T]/g, "").slice(0, 14)}`;
+}
+
+/** Files that make up a task's temporary working state (§20). */
+const TASK_ARTIFACTS = ["proposal.md", "plan.md", "designer.md", "backend.md", "qa.md"];
+
+/**
+ * §20: on completion the scratchpads are deleted while the distilled
+ * knowledge, decisions, and the task's own state.json record are retained.
+ */
+export function removeTaskScratchpads(root: string, configDir: string, taskId: string): void {
+  const dir = taskDir(dataRoot(root, configDir), taskId);
+  if (!existsSync(dir)) return;
+  for (const file of TASK_ARTIFACTS) rmSync(join(dir, file), { force: true });
+  for (const file of readdirSync(dir)) {
+    if (file.startsWith("scout-")) rmSync(join(dir, file), { force: true });
+  }
+}
+
+/** Delete the temporary task dir after knowledge has been distilled. */
+export function cleanupTaskDir(root: string, configDir: string, taskId: string): void {
+  rmSync(taskDir(dataRoot(root, configDir), taskId), { recursive: true, force: true });
+}

package/src/state/project.ts

@@ -0,0 +1,99 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { DEFAULT_CONFIG, resolveConfig, type BotLobbyConfig } from "../schemas/configuration.ts";
+
+const DEFAULT_CONFIG_DIR = ".pi";
+
+/** Live per-project tree name; every write targets it. */
+const DATA_DIR = "bot-lobby";
+
+/** Pre-rename per-project tree names, newest first; read-only fallbacks. */
+const LEGACY_DATA_DIRS = ["dev-lobby", "dev-house"] as const;
+
+type LegacyDataDir = (typeof LEGACY_DATA_DIRS)[number];
+
+/** Walk up to the nearest ancestor holding a config dir or git root. */
+export function detectProjectRoot(cwd: string, configDir = DEFAULT_CONFIG_DIR): string {
+  let dir = resolve(cwd);
+  for (;;) {
+    if (existsSync(join(dir, configDir)) || existsSync(join(dir, ".git"))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return resolve(cwd);
+    dir = parent;
+  }
+}
+
+/** Root of all per-project bot-lobby data: <root>/<configDir>/bot-lobby. Every write targets it. */
+export function dataRoot(root: string, configDir = DEFAULT_CONFIG_DIR): string {
+  return join(root, configDir, DATA_DIR);
+}
+
+/** One pre-rename per-project root by tree name; read-only. */
+export function legacyDataRoot(root: string, configDir = DEFAULT_CONFIG_DIR, name: LegacyDataDir = LEGACY_DATA_DIRS[0]): string {
+  return join(root, configDir, name);
+}
+
+/** Pre-rename trees that exist on disk, newest first. */
+function existingLegacyRoots(root: string, configDir: string): string[] {
+  return LEGACY_DATA_DIRS.map((name) => legacyDataRoot(root, configDir, name)).filter((dir) => existsSync(dir));
+}
+
+/**
+ * Roots that merged reads walk, newest first: the bot-lobby tree always, then
+ * every existing pre-rename tree (dev-lobby, then dev-house). Readers take the
+ * first root that has a task id or a knowledge file, so pre-rename data stays
+ * visible per task and per file instead of vanishing as soon as any bot-lobby
+ * data exists.
+ */
+export function readDataRoots(root: string, configDir = DEFAULT_CONFIG_DIR): string[] {
+  return [dataRoot(root, configDir), ...existingLegacyRoots(root, configDir)];
+}
+
+/** Newest existing pre-rename tree, if any; seeding reads it, writes never touch it. */
+export function firstLegacyDataRoot(root: string, configDir = DEFAULT_CONFIG_DIR): string | undefined {
+  return existingLegacyRoots(root, configDir)[0];
+}
+
+/**
+ * Root of the user-global bot-lobby config. Config is global so one setup
+ * applies to every project; tasks and knowledge stay per-project. Tests point
+ * `BOT_LOBBY_CONFIG_DIR` at a temp directory.
+ */
+export function globalConfigDir(): string {
+  return process.env.BOT_LOBBY_CONFIG_DIR ?? join(homedir(), ".pi", "bot-lobby");
+}
+
+export function globalConfigPath(): string {
+  return join(globalConfigDir(), "config.json");
+}
+
+/**
+ * Config source for reads: the bot-lobby config when it exists, otherwise the
+ * newest existing pre-rename one (dev-lobby, then dev-house). An explicit
+ * `BOT_LOBBY_CONFIG_DIR` overrides (tests, custom setups) and never falls back,
+ * so legacy dirs stay out of hermetic tests.
+ */
+function configSourcePath(): string {
+  if (process.env.BOT_LOBBY_CONFIG_DIR !== undefined) return globalConfigPath();
+  const candidates = [globalConfigPath(), ...LEGACY_DATA_DIRS.map((dir) => join(homedir(), ".pi", dir, "config.json"))];
+  return candidates.find((path) => existsSync(path)) ?? candidates[0]!;
+}
+
+/** Load the global config; fall back to defaults on any read/parse error. */
+export function loadConfig(): BotLobbyConfig {
+  try {
+    return resolveConfig(JSON.parse(readFileSync(configSourcePath(), "utf8")));
+  } catch {
+    return DEFAULT_CONFIG;
+  }
+}
+
+/** Persist the global config through a temp file + rename so a crash cannot truncate it. */
+export function saveConfig(config: BotLobbyConfig): void {
+  mkdirSync(globalConfigDir(), { recursive: true });
+  const target = globalConfigPath();
+  const tmp = `${target}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(config, null, 2)}\n`);
+  renameSync(tmp, target);
+}

package/src/state/task-state.ts

@@ -0,0 +1,22 @@
+import type { Task, TaskState } from "../schemas/task.ts";
+import { assertTransition } from "../workflow/transitions.ts";
+
+/**
+ * Single mutation point for task state. Every state change flows through here
+ * so the engine — not any agent — is the only thing that can move a task.
+ */
+export type TransitionListener = (task: Task, to: TaskState) => void;
+
+let listener: TransitionListener | undefined;
+
+/** Install the single transition observer (the extension's attention notifier). */
+export function onTransition(fn: TransitionListener): void {
+  listener = fn;
+}
+
+export function transition(task: Task, to: TaskState, now = new Date().toISOString()): void {
+  assertTransition(task.state, to);
+  task.state = to;
+  task.updatedAt = now;
+  listener?.(task, to);
+}

package/src/text.ts

@@ -0,0 +1,51 @@
+/** Truncate text to a character budget, marking how much was omitted. */
+export function truncate(text: string, maxChars: number): string {
+  if (maxChars <= 0) return "";
+  if (text.length <= maxChars) return text;
+  return `${text.slice(0, maxChars)}\n[...${text.length - maxChars} characters omitted]`;
+}
+
+/** Filler and imperative words that carry no topic signal in a request. */
+const FILLER_WORDS = new Set([
+  "let's",
+  "lets",
+  "please",
+  "can",
+  "you",
+  "could",
+  "i",
+  "we",
+  "want",
+  "need",
+  "would",
+  "like",
+  "to",
+  "help",
+  "me",
+  "a",
+  "an",
+  "the",
+  "for",
+  "our",
+  "my",
+]);
+
+/** Case- and punctuation-insensitive key used to match a word against the fillers. */
+function fillerKey(word: string): string {
+  return word
+    .toLowerCase()
+    .replace(/[\u2018\u2019\u02bc]/g, "'")
+    .replace(/[^a-z0-9']/g, "");
+}
+
+/**
+ * The first `maxWords` content words of a request, used as the short task title.
+ * Deterministic and total: whitespace-only input yields `""`, and a request
+ * made entirely of filler words falls back to its raw first words.
+ */
+export function shortTitle(request: string, maxWords = 3): string {
+  if (maxWords <= 0) return "";
+  const words = request.trim().split(/\s+/).filter(Boolean);
+  const content = words.filter((word) => !FILLER_WORDS.has(fillerKey(word)));
+  return (content.length > 0 ? content : words).slice(0, maxWords).join(" ");
+}

package/src/workflow/approvals.ts

@@ -0,0 +1,45 @@
+import type { Approval, ApprovalKind, Task } from "../schemas/task.ts";
+import type { Domain } from "../schemas/agent.ts";
+
+/** Record a Worker-requested exception so it blocks further work until resolved. */
+export function requestApproval(
+  task: Task,
+  kind: ApprovalKind,
+  domain: Domain,
+  detail: string,
+  now = new Date().toISOString(),
+): Approval {
+  const approval: Approval = { id: `APR-${task.approvals.length + 1}`, kind, domain, detail, status: "pending", createdAt: now };
+  task.approvals.push(approval);
+  return approval;
+}
+
+export function pendingApprovals(task: Task, domain?: Domain): Approval[] {
+  return task.approvals.filter(
+    (approval) => approval.status === "pending" && (domain === undefined || approval.domain === domain),
+  );
+}
+
+export function resolveApproval(
+  task: Task,
+  id: string,
+  status: "approved" | "rejected",
+  note?: string,
+): Approval | undefined {
+  const approval = task.approvals.find((entry) => entry.id === id && entry.status === "pending");
+  if (!approval) return undefined;
+  approval.status = status;
+  approval.note = note;
+  return approval;
+}
+
+/**
+ * Engine gate: a domain cannot keep implementing while it has an unresolved
+ * dependency or architecture request.
+ */
+export function assertNoPendingApprovals(task: Task, domain: Domain): void {
+  const pending = pendingApprovals(task, domain);
+  if (pending.length === 0) return;
+  const list = pending.map((approval) => `${approval.id} (${approval.kind}): ${approval.detail}`).join("; ");
+  throw new Error(`${domain} has unresolved approvals — resolve them first: ${list}`);
+}

package/src/workflow/transitions.ts

@@ -0,0 +1,41 @@
+import { TERMINAL_STATES, type TaskState } from "../schemas/task.ts";
+
+/**
+ * Workflow transitions per the build plan §8. These are the only legal
+ * workflow moves; the engine enforces them regardless of what any agent asks.
+ */
+export const TRANSITIONS: Record<TaskState, readonly TaskState[]> = {
+  created: ["clarifying"],
+  clarifying: ["scouting", "awaiting_approval"],
+  scouting: ["synthesizing"],
+  synthesizing: ["awaiting_approval"],
+  awaiting_approval: ["planning", "abandoned"],
+  planning: ["implementing"],
+  implementing: ["reviewing", "blocked"],
+  reviewing: ["implementing", "completed", "blocked"],
+  blocked: ["implementing", "abandoned"],
+  completed: [],
+  abandoned: [],
+};
+
+/** User cancellation / decline abandons from any non-terminal state. */
+export function canAbandon(state: TaskState): boolean {
+  return !TERMINAL_STATES.includes(state);
+}
+
+export function canTransition(from: TaskState, to: TaskState): boolean {
+  if (to === "abandoned") return canAbandon(from);
+  if (from === to) return !TERMINAL_STATES.includes(from);
+  return (TRANSITIONS[from] as readonly TaskState[]).includes(to);
+}
+
+export function nextStates(from: TaskState): readonly TaskState[] {
+  const base = TRANSITIONS[from];
+  return canAbandon(from) && !base.includes("abandoned") ? [...base, "abandoned"] : base;
+}
+
+export function assertTransition(from: TaskState, to: TaskState): void {
+  if (!canTransition(from, to)) {
+    throw new Error(`Invalid state transition: ${from} -> ${to}`);
+  }
+}