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

package/src/pi/commands.ts

@@ -0,0 +1,268 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { TERMINAL_STATES, createTask, taskRequest, type Task } from "../schemas/task.ts";
+import { detectProjectRoot, globalConfigPath, loadConfig, readDataRoots } from "../state/project.ts";
+import {
+  activeTask,
+  claimTask,
+  ownedTask,
+  ownerlessTask,
+  createTaskDir,
+  ensureProjectStructure,
+  nextTaskId,
+  saveTask,
+  selectTask,
+  taskDirFor,
+  taskHealth,
+} from "../state/persistence.ts";
+import { transition } from "../state/task-state.ts";
+import { AGENT_DIR_NAMES, KNOWLEDGE_FILES, knowledgeDir, type KnowledgeAgent } from "../knowledge/paths.ts";
+import { readFirstExisting } from "../knowledge/store.ts";
+import { overThreshold } from "../knowledge/compactor.ts";
+import { applyApprovalChoice, describeTask, describeOversizedKnowledge, type ApprovalChoice } from "../workflow/workflow.ts";
+import { shortTitle } from "../text.ts";
+import { applyStatus, registerRevealShortcut, setMinimized } from "./ui.ts";
+import { applyMasterModel, openSettings } from "./settings-ui.ts";
+
+const HELP = [
+  "/bot-lobby <request>        Start a task through the workflow",
+  "/bot-lobby status [taskId]  Show the active task",
+  "/bot-lobby tasks            List tasks",
+  "/bot-lobby pause|resume     Pause or resume the active task",
+  "/bot-lobby cancel [taskId]  Abandon a task",
+  "/bot-lobby approve|amend <text>|decline   Answer the current proposal",
+  "/bot-lobby knowledge        Show persistent knowledge files",
+  "/bot-lobby settings         Edit per-agent model/thinking/instructions",
+  "/bot-lobby config           Show effective configuration",
+  "/bot-lobby minimize|restore   Hide or restore bot-lobby for this session (ctrl+shift+m)",
+  "/bot-lobby claim <taskId>    Take ownership of an orphaned task",
+].join("\n");
+
+/** Subcommands only win when no free-form text follows (so tasks still start). */
+const SUBCOMMANDS = new Set(["status", "tasks", "pause", "resume", "cancel", "approve", "amend", "decline", "knowledge", "config", "settings", "minimize", "restore", "claim"]);
+
+function isTaskId(value: string | undefined): boolean {
+  return Boolean(value && /^TASK-/.test(value));
+}
+
+function parseCommand(args: string): { sub: string | undefined; rest: string[]; restText: string } {
+  const trimmed = args.trim();
+  const [sub, ...rest] = trimmed.split(/\s+/).filter(Boolean);
+  if (!sub || !SUBCOMMANDS.has(sub)) return { sub: undefined, rest: [], restText: trimmed };
+  if (sub !== "amend" && sub !== "claim" && rest.length > 0 && !(rest.length === 1 && isTaskId(rest[0]))) {
+    return { sub: undefined, rest: [], restText: trimmed };
+  }
+  return { sub, rest, restText: trimmed.slice(sub.length).trim() };
+}
+
+function uniqueTaskId(root: string, configDir: string, request: string): string {
+  const base = nextTaskId(request);
+  let id = base;
+  let suffix = 2;
+  while (existsSync(taskDirFor(root, configDir, id))) id = `${base}-${suffix++}`;
+  return id;
+}
+
+export function kickoff(task: Task): string {
+  return [
+    `A bot-lobby task is active: ${task.id}`,
+    `Title: ${task.title}`,
+    `Request: ${taskRequest(task)}`,
+    `State: ${task.state}`,
+    "",
+    "Drive it with the orchestrate tool:",
+    "1. clarify if the request is genuinely ambiguous,",
+    "2. scout the domains the request touches,",
+    "3. synthesize the findings and propose a short `- ` bullet list for approval.",
+    "Do not implement anything before the user approves the proposal.",
+  ].join("\n");
+}
+
+async function startTask(
+  pi: ExtensionAPI,
+  ctx: ExtensionCommandContext,
+  configDir: string,
+  request: string,
+): Promise<void> {
+  const root = detectProjectRoot(ctx.cwd, configDir);
+  ensureProjectStructure(root, configDir);
+  const sessionId = ctx.sessionManager.getSessionId();
+  const existing = ownedTask(root, configDir, sessionId);
+  if (existing) {
+    ctx.ui.notify(`bot-lobby ${existing.id} is already active in this session. Finish it or run /bot-lobby cancel ${existing.id} first.`, "warning");
+    return;
+  }
+  const task = createTask(uniqueTaskId(root, configDir, request), shortTitle(request), new Date().toISOString(), request, sessionId);
+  createTaskDir(root, configDir, task);
+  transition(task, "clarifying");
+  saveTask(root, configDir, task);
+  applyStatus(ctx, root, configDir);
+  await applyMasterModel(pi, ctx, loadConfig());
+  ctx.ui.notify(`bot-lobby ${task.id} started`, "info");
+  pi.sendUserMessage(kickoff(task));
+}
+
+function showStatus(ctx: ExtensionCommandContext, configDir: string, taskId?: string): void {
+  const root = detectProjectRoot(ctx.cwd, configDir);
+  const sessionId = ctx.sessionManager.getSessionId();
+  const task = selectTask(root, configDir, taskId, sessionId) ?? (taskId ? undefined : ownerlessTask(root, configDir));
+  applyStatus(ctx, root, configDir);
+  const oversized = describeOversizedKnowledge(readDataRoots(root, configDir), loadConfig().knowledge.compactionThreshold);
+  const broken = taskHealth(root, configDir).corrupted;
+  const knowledge = [
+    oversized.length > 0 ? `Knowledge over threshold: ${oversized.join(", ")}` : "",
+    broken.length > 0 ? `Unreadable task state: ${broken.join(", ")}` : "",
+  ].filter(Boolean).join("\n");
+  const footer = knowledge ? `\n${knowledge}` : "";
+  ctx.ui.notify(task ? `${describeTask(task)}${footer}` : `No bot-lobby task found in ${root}.${footer}`, task ? "info" : "warning");
+}
+
+function showTasks(ctx: ExtensionCommandContext, configDir: string): void {
+  const root = detectProjectRoot(ctx.cwd, configDir);
+  const { tasks, corrupted } = taskHealth(root, configDir);
+  if (tasks.length === 0 && corrupted.length === 0) return ctx.ui.notify("No bot-lobby tasks yet.", "info");
+  const lines = tasks.slice(0, 12).map((task) => `${task.id}  ${task.state.padEnd(17)} ${(task.ownerSessionId ? task.ownerSessionId.slice(0, 8) : "—").padEnd(9)} ${task.title.slice(0, 60)}`);
+  if (corrupted.length > 0) lines.push("", `Unreadable task state: ${corrupted.join(", ")} (left untouched; inspect ${readDataRoots(root, configDir).join(" and ")}/tasks)`);
+  ctx.ui.notify(lines.join("\n"), "info");
+}
+
+function setPaused(ctx: ExtensionCommandContext, configDir: string, paused: boolean, taskId?: string): void {
+  const root = detectProjectRoot(ctx.cwd, configDir);
+  const task = selectTask(root, configDir, taskId, ctx.sessionManager.getSessionId());
+  if (task?.ownerSessionId && task.ownerSessionId !== ctx.sessionManager.getSessionId()) {
+    return ctx.ui.notify(`${task.id} is owned by another pi session; /bot-lobby claim ${task.id} to take it over.`, "warning");
+  }
+  if (!task || TERMINAL_STATES.includes(task.state)) {
+    return ctx.ui.notify("No active task to pause or resume.", "warning");
+  }
+  task.paused = paused;
+  saveTask(root, configDir, task);
+  applyStatus(ctx, root, configDir);
+  ctx.ui.notify(`${task.id} ${paused ? "paused" : "resumed"}.`, "info");
+}
+
+function cancelTask(ctx: ExtensionCommandContext, configDir: string, taskId?: string): void {
+  const root = detectProjectRoot(ctx.cwd, configDir);
+  const task = selectTask(root, configDir, taskId, ctx.sessionManager.getSessionId());
+  if (task?.ownerSessionId && task.ownerSessionId !== ctx.sessionManager.getSessionId()) {
+    return ctx.ui.notify(`${task.id} is owned by another pi session; /bot-lobby claim ${task.id} to take it over.`, "warning");
+  }
+  if (!task) return ctx.ui.notify("No task to cancel.", "warning");
+  if (TERMINAL_STATES.includes(task.state)) return ctx.ui.notify(`${task.id} is already ${task.state}.`, "warning");
+  transition(task, "abandoned");
+  saveTask(root, configDir, task);
+  applyStatus(ctx, root, configDir);
+  ctx.ui.notify(`${task.id} abandoned.`, "info");
+}
+
+/** Explicit takeover of an orphaned task (ownerless, or owned by a dead session). */
+function claimTaskCommand(ctx: ExtensionCommandContext, configDir: string, taskId?: string): void {
+  if (!isTaskId(taskId)) return ctx.ui.notify("Usage: /bot-lobby claim <taskId>", "warning");
+  const root = detectProjectRoot(ctx.cwd, configDir);
+  const sessionId = ctx.sessionManager.getSessionId();
+  const current = ownedTask(root, configDir, sessionId);
+  if (current && current.id !== taskId) {
+    return ctx.ui.notify(`bot-lobby ${current.id} is already active in this session; cancel it before claiming ${taskId}.`, "warning");
+  }
+  const claimed = claimTask(root, configDir, taskId!, sessionId);
+  if (!claimed) return ctx.ui.notify(`No task ${taskId}.`, "warning");
+  applyStatus(ctx, root, configDir);
+  ctx.ui.notify(`bot-lobby now owns ${claimed.id}.`, "info");
+}
+function answerProposal(
+  ctx: ExtensionCommandContext,
+  configDir: string,
+  choice: ApprovalChoice,
+  amendment?: string,
+): void {
+  const root = detectProjectRoot(ctx.cwd, configDir);
+  const task = activeTask(root, configDir, ctx.sessionManager.getSessionId());
+  if (!task) return ctx.ui.notify("No active task.", "warning");
+  try {
+    const message = applyApprovalChoice(task, choice, amendment);
+    saveTask(root, configDir, task);
+    applyStatus(ctx, root, configDir);
+    ctx.ui.notify(message, "info");
+  } catch (error) {
+    ctx.ui.notify(`bot-lobby: ${(error as Error).message}`, "warning");
+  }
+}
+
+function showKnowledge(ctx: ExtensionCommandContext, configDir: string): void {
+  const root = detectProjectRoot(ctx.cwd, configDir);
+  const cfg = loadConfig();
+  const roots = readDataRoots(root, configDir);
+  const threshold = cfg.knowledge.compactionThreshold;
+  const lines: string[] = [`Threshold: ${threshold} chars`];
+  for (const agent of Object.keys(AGENT_DIR_NAMES) as KnowledgeAgent[]) {
+    const sizes = KNOWLEDGE_FILES[agent].map((file) => {
+      const chars = readFirstExisting(roots.map((dr) => join(knowledgeDir(dr, agent), file))).length;
+      return `${file}=${chars}${chars > threshold ? " OVER" : ""}`;
+    });
+    lines.push(`${AGENT_DIR_NAMES[agent]}: ${sizes.join(" ")}`);
+  }
+  const oversized = overThreshold(roots, threshold);
+  if (oversized.length > 0) lines.push("", "Ask the Master to compact the files marked OVER.");
+  ctx.ui.notify(lines.join("\n"), "info");
+}
+
+function showConfig(ctx: ExtensionCommandContext): void {
+  ctx.ui.notify(`${globalConfigPath()}\n${JSON.stringify(loadConfig(), null, 2)}`, "info");
+}
+
+export function registerCommands(pi: ExtensionAPI, configDir: string): void {
+  registerRevealShortcut(pi, configDir);
+  pi.registerCommand("bot-lobby", {
+    description: "Structured multi-agent engineering orchestrator",
+    getArgumentCompletions: (prefix) => {
+      const items = [...SUBCOMMANDS].map((value) => ({ value, label: value }));
+      const filtered = items.filter((item) => item.value.startsWith(prefix));
+      return filtered.length > 0 ? filtered : null;
+    },
+    handler: async (args, ctx) => {
+      const { sub, rest, restText } = parseCommand(args ?? "");
+      if (!sub) {
+        if (!restText) return ctx.ui.notify(HELP, "info");
+        return startTask(pi, ctx, configDir, restText);
+      }
+      switch (sub) {
+        case "status":
+          return showStatus(ctx, configDir, rest[0]);
+        case "tasks":
+          return showTasks(ctx, configDir);
+        case "pause":
+          return setPaused(ctx, configDir, true, rest[0]);
+        case "resume":
+          return setPaused(ctx, configDir, false, rest[0]);
+        case "cancel":
+          return cancelTask(ctx, configDir, rest[0]);
+        case "approve":
+          return answerProposal(ctx, configDir, "approve");
+        case "amend":
+          return answerProposal(ctx, configDir, "amend", restText);
+        case "decline":
+          return answerProposal(ctx, configDir, "decline");
+        case "knowledge":
+          return showKnowledge(ctx, configDir);
+        case "settings":
+          return openSettings(pi, ctx);
+        case "minimize":
+          setMinimized(true);
+          return applyStatus(ctx, detectProjectRoot(ctx.cwd, configDir), configDir);
+        case "restore":
+          setMinimized(false);
+          return applyStatus(ctx, detectProjectRoot(ctx.cwd, configDir), configDir);
+        case "claim":
+          return claimTaskCommand(ctx, configDir, rest[0]);
+        default:
+          return showConfig(ctx);
+      }
+    },
+  });
+
+  pi.registerCommand("bot-lobby-settings", {
+    description: "Edit per-agent model, thinking, and instructions",
+    handler: async (_args, ctx) => openSettings(pi, ctx),
+  });
+}

package/src/pi/events.ts

@@ -0,0 +1,76 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { activeTask } from "../state/persistence.ts";
+import { detectProjectRoot, loadConfig, readDataRoots } from "../state/project.ts";
+import { compilePrompt } from "../prompts/compiler.ts";
+import { readAgentKnowledge } from "../knowledge/store.ts";
+import { selectKnowledge } from "../knowledge/selector.ts";
+import { cancelAllRuns } from "../execution/agent-runner.ts";
+import { describeTask } from "../workflow/workflow.ts";
+import { truncate } from "../text.ts";
+import { applyStatus, clearStatus, isMinimized, setMinimized, setOracleActivity } from "./ui.ts";
+import { oracleActivityWord } from "./activity.ts";
+import { isSubagentProcess, visibleTools } from "./quiet.ts";
+import { registerQuietTools } from "./tool-renderers.ts";
+import { taskRequest, type Task } from "../schemas/task.ts";
+
+function masterTaskContext(task: Task): string {
+  return [
+    `Task ${task.id}: ${task.title}`,
+    `Request: ${truncate(taskRequest(task), 2000)}`,
+    task.proposal ? `Current proposal:\n${truncate(task.proposal, 2000)}` : "",
+    task.plan ? `Approved plan:\n${truncate(task.plan, 3000)}` : "",
+    task.amendments.length > 0 ? `User amendments:\n${task.amendments.map((entry) => `- ${entry}`).join("\n")}` : "",
+  ]
+    .filter((line) => line.length > 0)
+    .join("\n\n");
+}
+
+/**
+ * While a bot-lobby task is active the main agent acts as the Master, so its
+ * operating prompt is patched into the system prompt as one cache-stable
+ * section rather than replacing the whole prompt.
+ */
+export function registerLifecycle(pi: ExtensionAPI, configDir: string): void {
+  pi.on("session_start", (_event, ctx) => {
+    // Master-only: subagents keep their own --tools allowlist (see quiet.ts).
+    if (!isSubagentProcess()) {
+      registerQuietTools(pi);
+      pi.setActiveTools(visibleTools(pi.getActiveTools()));
+    }
+    const root = detectProjectRoot(ctx.cwd, configDir);
+    setMinimized(false);
+    applyStatus(ctx, root, configDir);
+  });
+
+
+  // The oracle spinner mirrors the master's own tool calls; subagents report into runs.
+  pi.on("tool_execution_start", (event) => {
+    if (!isSubagentProcess()) setOracleActivity(oracleActivityWord(event.toolName, event.args));
+  });
+  pi.on("session_shutdown", (_event, ctx) => {
+    cancelAllRuns();
+    clearStatus(ctx);
+  });
+
+  pi.on("before_agent_start", (event, ctx) => {
+    const root = detectProjectRoot(ctx.cwd, configDir);
+    const sessionId = ctx.sessionManager.getSessionId();
+    const task = isSubagentProcess() || isMinimized() ? undefined : activeTask(root, configDir, sessionId);
+    if (!task) {
+      delete event.systemPromptOptions.sections["bot-lobby"];
+      return;
+    }
+    const slices = readAgentKnowledge(readDataRoots(root, configDir), "master");
+    const selected = selectKnowledge(`${taskRequest(task)} ${task.proposal ?? ""}`, slices);
+    event.systemPromptOptions.sections["bot-lobby"] = compilePrompt({
+      domain: "master",
+      task: masterTaskContext(task),
+      standards: selected.standards,
+      knowledge: selected.knowledge,
+      decisions: selected.decisions,
+      workflowContext: describeTask(task),
+      instructions: loadConfig().master.instructions,
+    });
+  });
+}
+

package/src/pi/expressions.ts

@@ -0,0 +1,101 @@
+/**
+ * Caller-driven expression schedule for the zen sprites.
+ *
+ * Pure and deterministic: `now` and the random source are always injected, so
+ * the art, layout and metrics stay free of `Date.now`/`Math.random`. Each slot
+ * and the oracle keeps its own state, holds its rest frame between events and,
+ * after a random 20-30 s gap, plays a short blink or a longer emote.
+ */
+
+/** Resting gap before the next expression, milliseconds. */
+export const BLINK_MIN_MS = 20_000;
+export const BLINK_MAX_MS = 30_000;
+/** How long one blink and one emote are held. */
+export const BLINK_MS = 500;
+export const EMOTE_MS = 2000;
+/** Fast clock while an expression plays, short enough that a blink is never skipped. */
+export const FAST_TICK_MS = 120;
+
+/** Art frame indexes: 0 rests, 1 blinks, `2 ..` are emotes. */
+export const REST_FRAME = 0;
+export const BLINK_FRAME = 1;
+export const EMOTE_FRAME = 2;
+/** Emote frame range: `EMOTE_FRAME .. EMOTE_FRAME + EMOTE_FRAMES - 1`; an emote steps through them. */
+export const EMOTE_FRAMES = 2;
+/** Each emote frame is held this long, so an emote steps through its frames. */
+export const EMOTE_STEP_MS = Math.floor(EMOTE_MS / EMOTE_FRAMES);
+
+const BLINK_CHANCE = 0.65;
+
+export interface ExpressionState {
+  /** Earliest `now` the next expression may start. */
+  nextAt: number;
+  /** When the playing expression ends; not after `now` while resting. */
+  until: number;
+  /** When the current expression started; drives emote frame stepping. */
+  startedAt: number;
+  /** Frame index for the art: 0 rest, 1 blink, 2+ emote. */
+  frame: number;
+}
+
+/** A random draw clamped to `[0, 1]`, so a non-finite source value can never leak. */
+function unit(rng: () => number): number {
+  const value = rng();
+  return Number.isFinite(value) ? Math.min(1, Math.max(0, value)) : 0;
+}
+
+/** Random resting gap before the next expression, in `[BLINK_MIN_MS, BLINK_MAX_MS]`. */
+export function nextGap(rng: () => number): number {
+  return BLINK_MIN_MS + Math.round(unit(rng) * (BLINK_MAX_MS - BLINK_MIN_MS));
+}
+
+/** Whether the next expression blinks (~65%) or emotes (~35%). */
+export function pickEvent(rng: () => number): "blink" | "emote" {
+  return unit(rng) < BLINK_CHANCE ? "blink" : "emote";
+}
+
+/** A freshly rested expression that fires for the first time after one random gap. */
+export function createExpression(now: number, rng: () => number): ExpressionState {
+  const start = Number.isFinite(now) ? now : 0;
+  return { nextAt: start + nextGap(rng), until: start, startedAt: start, frame: REST_FRAME };
+}
+
+/** True while `now` is inside a playing blink or emote. */
+export function isPlaying(state: ExpressionState, now: number): boolean {
+  return Number.isFinite(now) && now < state.until;
+}
+
+/** True when any state is mid-expression; the caller uses it to retime its clock. */
+export function anyPlaying(states: readonly ExpressionState[], now: number): boolean {
+  return states.some((state) => isPlaying(state, now));
+}
+
+/**
+ * Advance one sprite to `now`: start a blink or emote once the gap has elapsed,
+ * drop back to the rest frame when it ends, and change nothing in between.
+ */
+export function advanceExpression(state: ExpressionState, now: number, rng: () => number): ExpressionState {
+  if (!Number.isFinite(now)) return state;
+  if (now < state.until) return state.frame >= EMOTE_FRAME ? steppedEmote(state, now) : state;
+  if (now < state.nextAt) return state.frame === REST_FRAME ? state : { ...state, frame: REST_FRAME };
+  return play(now, rng);
+}
+
+function play(now: number, rng: () => number): ExpressionState {
+  const blink = pickEvent(rng) === "blink";
+  const until = now + (blink ? BLINK_MS : EMOTE_MS);
+  return { nextAt: until + nextGap(rng), until, startedAt: now, frame: blink ? BLINK_FRAME : EMOTE_FRAME };
+}
+
+/** Emote frame for `now`: one step per EMOTE_STEP_MS, clamped to the last frame. */
+function emoteFrameAt(startedAt: number, now: number): number {
+  const elapsed = now - startedAt;
+  const step = Number.isFinite(elapsed) && elapsed > 0 ? Math.floor(elapsed / EMOTE_STEP_MS) : 0;
+  return EMOTE_FRAME + Math.min(EMOTE_FRAMES - 1, Math.max(0, step));
+}
+
+/** Advance an in-flight emote's frame, keeping the same object when it has not changed. */
+function steppedEmote(state: ExpressionState, now: number): ExpressionState {
+  const frame = emoteFrameAt(state.startedAt, now);
+  return frame === state.frame ? state : { ...state, frame };
+}