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

package/src/pi/tool-renderers.ts

@@ -0,0 +1,121 @@
+import type { ExtensionAPI, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import {
+  createBashToolDefinition,
+  createEditToolDefinition,
+  createFindToolDefinition,
+  createGrepToolDefinition,
+  createLsToolDefinition,
+  createReadToolDefinition,
+  createWriteToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+import { Container, Text } from "@earendil-works/pi-tui";
+import { truncate } from "../text.ts";
+import { isQuiet, isSubagentProcess } from "./quiet.ts";
+
+type BuiltinName = "read" | "bash" | "edit" | "write" | "grep" | "find" | "ls";
+
+/** Built-in factories; their definitions carry the metadata the model needs. */
+const FACTORIES: Record<BuiltinName, (cwd: string) => ToolDefinition<any, any, any>> = {
+  read: createReadToolDefinition,
+  bash: createBashToolDefinition,
+  edit: createEditToolDefinition,
+  write: createWriteToolDefinition,
+  grep: createGrepToolDefinition,
+  find: createFindToolDefinition,
+  ls: createLsToolDefinition,
+};
+
+const ARG_CHARS = 100;
+const OUTPUT_CHARS = 2000;
+
+/** Minimal theme surface used by the renderers, so they stay easy to unit test. */
+interface RenderTheme {
+  fg(color: "accent" | "dim" | "error" | "muted" | "success" | "toolTitle", text: string): string;
+  bold(text: string): string;
+}
+
+const definitions = new Map<string, ToolDefinition<any, any, any>>();
+
+/** Cache one factory definition per cwd so execution keeps the session's cwd. */
+function definitionFor(name: BuiltinName, cwd: string): ToolDefinition<any, any, any> {
+  const key = `${cwd}\0${name}`;
+  let definition = definitions.get(key);
+  if (!definition) {
+    definition = FACTORIES[name](cwd);
+    definitions.set(key, definition);
+  }
+  return definition;
+}
+
+function primaryArg(name: BuiltinName, args: unknown): string {
+  const record = (typeof args === "object" && args !== null ? args : {}) as Record<string, unknown>;
+  const raw = name === "bash" ? record.command : name === "grep" || name === "find" ? record.pattern : record.path;
+  return typeof raw === "string" ? raw : "";
+}
+
+/** One-line summary of a call: tool name and its primary argument. */
+function summarizeCall(name: BuiltinName, args: unknown): string {
+  const primary = primaryArg(name, args).replace(/\s+/g, " ").trim();
+  return truncate(primary.length > 0 ? primary : "…", ARG_CHARS);
+}
+
+function resultText(content: Array<{ type: string; text?: string }>): string {
+  return content
+    .filter((part) => part.type === "text" && typeof part.text === "string")
+    .map((part) => part.text as string)
+    .join("\n")
+    .trim();
+}
+
+function resultSummary(
+  name: BuiltinName,
+  args: unknown,
+  content: Array<{ type: string; text?: string }>,
+  expanded: boolean,
+  isError: boolean,
+  theme: RenderTheme,
+): string {
+  const icon = isError ? theme.fg("error", "✗") : theme.fg("success", "✓");
+  const body = resultText(content);
+  const head = `${icon} ${theme.fg("toolTitle", theme.bold(name))} ${theme.fg("accent", summarizeCall(name, args))}`;
+  if (!expanded || body.length === 0) return head;
+  return `${head}\n${theme.fg("dim", truncate(body, OUTPUT_CHARS))}`;
+}
+
+function callLine(name: BuiltinName, args: unknown, theme: RenderTheme): string {
+  return `${theme.fg("toolTitle", theme.bold(name))} ${theme.fg("accent", summarizeCall(name, args))}`;
+}
+
+/** Quiet-aware rendering; execution still delegates to the shipped factory. */
+function quietDefinition(name: BuiltinName, definition: ToolDefinition<any, any, any>): ToolDefinition<any, any, any> {
+  return {
+    ...definition,
+    renderShell: "self",
+    execute: (toolCallId, params, signal, onUpdate, ctx) =>
+      definitionFor(name, ctx.cwd).execute(toolCallId, params, signal, onUpdate, ctx),
+    renderCall: (args, theme) => (isQuiet() ? new Container() : new Text(callLine(name, args, theme), 0, 0)),
+    renderResult: (result, options, theme, ctx) =>
+      isQuiet()
+        ? new Container()
+        : new Text(resultSummary(name, ctx.args, result.content, options.expanded, ctx.isError, theme), 0, 0),
+  };
+}
+
+/**
+ * Replace pi's built-in tool definitions with quiet renderers. Called
+ * intentionally on every `session_start` (startup, reload, new, resume, fork):
+ * re-registering a name replaces that entry because the extension registry is a
+ * name-keyed Map (`registerTool` -> `extension.tools.set(name, ...)`), so this
+ * never accumulates duplicates. Spreading the factory definition keeps
+ * `promptSnippet`/`promptGuidelines`, so the model's tool guidance is unchanged.
+ * Must run after the extension runtime is bound because it reads `getAllTools()`
+ * to avoid registering phantom tools.
+ */
+export function registerQuietTools(pi: ExtensionAPI): void {
+  if (isSubagentProcess()) return;
+  const present = new Set(pi.getAllTools().map((tool) => tool.name));
+  for (const name of Object.keys(FACTORIES) as BuiltinName[]) {
+    if (!present.has(name)) continue;
+    pi.registerTool(quietDefinition(name, definitionFor(name, process.cwd())));
+  }
+}

package/src/pi/tools.ts

@@ -0,0 +1,158 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import type { AgentToolUpdateCallback, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Container, Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import type { AgentRun } from "../schemas/findings.ts";
+import type { ProcessRunner } from "../execution/pi-runner.ts";
+import { inheritThinking } from "../schemas/configuration.ts";
+import { detectProjectRoot, loadConfig } from "../state/project.ts";
+import { truncate } from "../text.ts";
+import { applyStatus, summarizeRun } from "./ui.ts";
+import { isQuiet } from "./quiet.ts";
+import {
+  ORCHESTRATE_ACTIONS,
+  runWorkflowAction,
+  type OrchestrateParams,
+  type WorkflowDeps,
+  type WorkflowResult,
+} from "../workflow/workflow.ts";
+
+const OrchestrateSchema = Type.Object({
+  action: StringEnum(ORCHESTRATE_ACTIONS, { description: "Workflow step to run" }),
+  taskId: Type.Optional(Type.String({ description: "Task id; defaults to the active task" })),
+  question: Type.Optional(Type.String({ description: "clarify: question for the user" })),
+  options: Type.Optional(Type.Array(Type.String(), { description: "clarify: optional answer choices" })),
+  domains: Type.Optional(Type.Array(Type.String(), { description: "scout: any of designer, backend, qa" })),
+  instruction: Type.Optional(Type.String({ description: "scout/research: what to investigate (for scout, also used to target-verify a claim)" })),
+  proposal: Type.Optional(Type.String({ description: "propose: the user-facing proposal as a short `- ` bullet list, one line per change" })),
+  concerns: Type.Optional(Type.Array(Type.String(), { description: "propose: concerns raised while challenging the request" })),
+  plan: Type.Optional(Type.String({ description: "plan: the detailed internal plan" })),
+  domain: Type.Optional(Type.String({ description: "implement/research: designer, backend, or qa" })),
+  task: Type.Optional(Type.String({ description: "implement: the concrete step for that domain's worker" })),
+  approvalId: Type.Optional(Type.String({ description: "resolve_approval: the approval id from a worker result" })),
+  decision: Type.Optional(
+    StringEnum(["approved", "rejected"] as const, { description: "resolve_approval: approve or reject the request" }),
+  ),
+  note: Type.Optional(Type.String({ description: "resolve_approval: rationale, or what to do instead when rejected" })),
+  reason: Type.Optional(Type.String({ description: "block: why the task cannot continue" })),
+  text: Type.Optional(Type.String({ description: "decide/complete/knowledge: the decision, completion summary, or knowledge text" })),
+  file: Type.Optional(Type.String({ description: "compact: the knowledge file to rewrite, e.g. knowledge.md" })),
+  kind: Type.Optional(
+    StringEnum(["knowledge", "standard", "decision", "completed"] as const, {
+      description: "knowledge: which persistent file the text belongs to",
+    }),
+  ),
+});
+
+const DESCRIPTION = [
+  "Drive the bot-lobby multi-agent workflow for the active task.",
+  "Actions: clarify (ask the user), scout (domain reconnaissance in parallel), research (summon the",
+  "read-only researcher for cited internet evidence on a complex change, tool, plugin, doc set or",
+  "dependency), propose (record the proposal and request approval), plan (record the internal",
+  "plan), implement (delegate one step to a domain worker), qa (final quality gate and the only",
+  "review), knowledge (record approved knowledge or a decision),",
+  "compact (replace a knowledge file with a rewritten version, archiving the old one),",
+  "resolve_approval (approve or reject a request), complete (declare the task done after the gates",
+  "pass), block/resume (escalate or continue), status, cancel.",
+  "The engine validates every step against the task state machine, so a rejected action means the workflow is not at that step yet.",
+].join(" ");
+
+/** Build the engine dependencies from the current Pi context. `thinking` is the live session level used by agents configured to inherit it. */
+export function workflowDeps(
+  ctx: ExtensionContext,
+  configDir: string,
+  signal: AbortSignal | undefined,
+  onUpdate: ((run: AgentRun) => void) | undefined,
+  runProcess?: ProcessRunner,
+  thinking?: string,
+): WorkflowDeps {
+  const root = detectProjectRoot(ctx.cwd, configDir);
+  const hasUI = ctx.hasUI;
+  return {
+    root,
+    configDir,
+    cwd: ctx.cwd,
+    config: inheritThinking(loadConfig(), thinking),
+    sessionId: ctx.sessionManager.getSessionId(),
+    signal,
+    onUpdate,
+    runProcess,
+    ask: async (question) => (hasUI ? ctx.ui.input(question) : undefined),
+    choose: async (title, options) => (hasUI ? ctx.ui.select(title, options) : undefined),
+    notify: (message, level = "info") => {
+      if (hasUI) ctx.ui.notify(message, level);
+    },
+  };
+}
+
+/** Accumulate agent runs so parallel scouts show as one progress list. */
+function runReporter(
+  update: AgentToolUpdateCallback<unknown> | undefined,
+  refresh: (runs: AgentRun[]) => void,
+): (run: AgentRun) => void {
+  const runs = new Map<string, AgentRun>();
+  return (run) => {
+    runs.set(`${run.domain}:${run.role}`, run);
+    const current = [...runs.values()];
+    refresh(current);
+    if (!update) return;
+    update({
+      content: [{ type: "text", text: current.map(summarizeRun).join("\n") }],
+      details: { runs: current },
+    });
+  };
+}
+
+/** TUI-only transcript entries; these never enter the model's context. */
+function registerBotLobbyEntries(pi: ExtensionAPI): void {
+  pi.registerEntryRenderer("bot-lobby", (entry, { expanded }, theme) => {
+    const data = entry.data as { kind?: string; taskId?: string; text?: string } | undefined;
+    const header = `bot-lobby ${data?.taskId ?? ""} — ${data?.kind ?? "note"}`.trim();
+    const body = data?.text ?? "";
+    return new Text(`${theme.fg("accent", theme.bold(header))}\n${theme.fg("toolOutput", expanded ? body : truncate(body, 600))}`, 0, 0);
+  });
+}
+
+export function registerOrchestrateTool(pi: ExtensionAPI, configDir: string, runProcess?: ProcessRunner): void {
+  registerBotLobbyEntries(pi);
+  pi.registerTool({
+    name: "orchestrate",
+    label: "Orchestrate",
+    description: DESCRIPTION,
+    promptSnippet: "Run a bot-lobby workflow step (clarify, scout, propose, plan, decide, status, cancel)",
+    promptGuidelines: [
+      "Use orchestrate for every bot-lobby workflow step; it enforces the task state machine and records results.",
+    ],
+    parameters: OrchestrateSchema,
+    // Self shell: an empty renderer then yields zero lines (see quiet.ts).
+    renderShell: "self",
+    async execute(_toolCallId, params, signal, onUpdate, ctx) {
+      const root = detectProjectRoot(ctx.cwd, configDir);
+      const deps = workflowDeps(ctx, configDir, signal, runReporter(onUpdate, (runs) => applyStatus(ctx, root, configDir, runs)), runProcess, pi.getThinkingLevel());
+      const result = await runWorkflowAction(params as OrchestrateParams, deps);
+      if (params.action === "propose" && params.proposal && result.ok) {
+        pi.appendEntry("bot-lobby", { kind: "proposal", taskId: params.taskId, text: params.proposal });
+      }
+      applyStatus(ctx, root, configDir);
+      return {
+        content: [{ type: "text", text: result.message }],
+        details: { ok: result.ok, state: result.state, taskId: result.taskId },
+      };
+    },
+    renderCall(args, theme) {
+      if (isQuiet()) return new Container();
+      const call = args as OrchestrateParams & { file?: string };
+      const target = call.domain ?? call.domains?.join(", ") ?? call.file ?? "";
+      const header = `${theme.fg("toolTitle", theme.bold("orchestrate"))} ${theme.fg("accent", call.action)}${target ? ` ${theme.fg("muted", target)}` : ""}`;
+      return new Text(header, 0, 0);
+    },
+    renderResult(result, { expanded }, theme) {
+      if (isQuiet()) return new Container();
+      const details = result.details as Partial<WorkflowResult> | undefined;
+      const body = result.content[0]?.type === "text" ? result.content[0].text : "";
+      const icon = details?.ok ? theme.fg("success", "✓") : theme.fg("warning", "!");
+      const header = `${icon} ${theme.fg("toolTitle", theme.bold("orchestrate"))} ${theme.fg("accent", details?.taskId ?? "")} ${theme.fg("muted", `→ ${details?.state ?? "?"}`)}`;
+      return new Text(expanded && body ? `${header}\n${theme.fg("dim", truncate(body, 2000))}` : header, 0, 0);
+    },
+  });
+}

package/src/pi/ui.ts

@@ -0,0 +1,227 @@
+import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
+import { Key, truncateToWidth, type Component, type TUI } from "@earendil-works/pi-tui";
+import type { AgentRun } from "../schemas/findings.ts";
+import { TERMINAL_STATES, type Task } from "../schemas/task.ts";
+import { activeTask } from "../state/persistence.ts";
+import { detectProjectRoot } from "../state/project.ts";
+import { advanceExpression, anyPlaying, createExpression, FAST_TICK_MS, type ExpressionState } from "./expressions.ts";
+import { SLOT_IDS } from "./mascot-art.ts";
+import { isQuiet, isSubagentProcess, toggleQuiet } from "./quiet.ts";
+import { panelLines, type ExpressionFrames } from "./zen.ts";
+
+export const STATUS_KEY = "bot-lobby";
+
+export function summarizeRun(run: AgentRun): string {
+  const icon = run.status === "running" ? "⏳" : run.status === "success" ? "✓" : "✗";
+  const state = run.status === "running" ? "" : ` (${run.status})`;
+  return `${icon} ${run.domain}/${run.role}${state}${run.attempts > 1 ? ` ×${run.attempts}` : ""}`;
+}
+
+/** One-line footer text, always carrying the quiet-mode hint. */
+export function statusText(task: Task | undefined, minimized = false): string {
+  const mode = isQuiet() ? "tools hidden (alt+t)" : "tools shown";
+  if (minimized) return `bot-lobby minimized (ctrl+shift+m) · ${mode}`;
+  if (!task) return `bot-lobby · ${mode}`;
+  return `bot-lobby ${task.id} · ${task.paused ? `${task.state} (paused)` : task.state} · ${mode}`;
+}
+
+let zenOn = false;
+let zenState: { task: Task | undefined; runs: AgentRun[] } = { task: undefined, runs: [] };
+
+/** Latest master tool activity; the oracle spinner line shows it. */
+let oracleActivity: string | undefined;
+
+/** Record the master's current activity word (see events.ts); undefined clears it. */
+export function setOracleActivity(activity: string | undefined): void {
+  oracleActivity = activity;
+}
+
+/** Upper bound on retained runs so a long task cannot grow the widget state without limit. */
+export const MAX_RETAINED_RUNS = 64;
+
+/**
+ * Merge `incoming` runs into `previous`, keyed by `runId`: a newer copy of a run
+ * replaces the old one and moves to the end (so `runs.at(-1)` stays the newest),
+ * order is otherwise preserved and only the newest `MAX_RETAINED_RUNS` survive.
+ */
+export function mergeRuns(previous: readonly AgentRun[], incoming: readonly AgentRun[]): AgentRun[] {
+  if (incoming.length === 0) return [...previous];
+  const merged = [...previous];
+  for (const run of incoming) {
+    const at = merged.findIndex((existing) => existing.runId === run.runId);
+    if (at >= 0) merged.splice(at, 1);
+    merged.push(run);
+  }
+  return merged.slice(-MAX_RETAINED_RUNS);
+}
+
+/** Per-session standard-pi mode: the widget and Master prompt are hidden but ownership stays. */
+let minimized = false;
+
+export function isMinimized(): boolean {
+  return minimized;
+}
+
+export function setMinimized(value: boolean): void {
+  minimized = value;
+}
+
+/** Flip minimize/restore and refresh the footer; the session is unchanged. */
+export function toggleMinimized(ctx: ExtensionContext, configDir: string): void {
+  setMinimized(!minimized);
+  applyStatus(ctx, detectProjectRoot(ctx.cwd, configDir), configDir, zenState.runs);
+  ctx.ui.notify(minimized ? "bot-lobby minimized — ctrl+shift+m or /bot-lobby restore to return" : "bot-lobby restored", "info");
+}
+
+export const LIVE_TICK_MS = 250;
+export const IDLE_TICK_MS = 1000;
+
+/** Fast frames while an agent works or the task is live; slow frames when it is quiet. */
+function isLive(): boolean {
+  if (zenState.runs.some((run) => run.status === "running")) return true;
+  const task = zenState.task;
+  return Boolean(task && !TERMINAL_STATES.includes(task.state) && !task.paused);
+}
+
+function liveTickDelay(): number {
+  return isLive() ? LIVE_TICK_MS : IDLE_TICK_MS;
+}
+
+/** Tick delay for the zen clock: fastest while an expression plays, so no blink or emote step is skipped. */
+export function expressionTickDelay(states: readonly ExpressionState[], now: number, live: boolean): number {
+  if (anyPlaying(states, now)) return FAST_TICK_MS;
+  return live ? LIVE_TICK_MS : IDLE_TICK_MS;
+}
+
+/** Every sprite with its own expression schedule. */
+type ExpressionKey = keyof ExpressionFrames;
+const EXPRESSION_KEYS: readonly ExpressionKey[] = [...SLOT_IDS, "oracle"];
+
+/** Animated zen scene + plan checklist shown above the editor while a task is active. */
+class ZenWidget implements Component {
+  private tick = 0;
+  private delay = liveTickDelay();
+  private timer: ReturnType<typeof setInterval>;
+  private disposed = false;
+  private readonly expressions: Record<ExpressionKey, ExpressionState>;
+  private readonly tui: TUI;
+  private readonly theme: () => Theme;
+  private readonly rng: () => number;
+
+  constructor(tui: TUI, theme: () => Theme, rng: () => number = Math.random) {
+    this.tui = tui;
+    this.theme = theme;
+    this.rng = rng;
+    const now = Date.now();
+    const entries = EXPRESSION_KEYS.map((key) => [key, createExpression(now, rng)] as const);
+    this.expressions = Object.fromEntries(entries) as Record<ExpressionKey, ExpressionState>;
+    this.timer = setInterval(() => this.advance(), this.delay);
+  }
+
+  private advance(): void {
+    if (this.disposed) return;
+    this.tick += 1;
+    const now = Date.now();
+    this.play(now);
+    this.retime(now);
+    this.tui.requestRender();
+  }
+
+  private play(now: number): void {
+    for (const key of EXPRESSION_KEYS) this.expressions[key] = advanceExpression(this.expressions[key], now, this.rng);
+  }
+
+  /** One interval, retimed when work starts or stops or an expression plays. */
+  private retime(now: number): void {
+    const delay = expressionTickDelay(Object.values(this.expressions), now, isLive());
+    if (delay === this.delay) return;
+    this.delay = delay;
+    clearInterval(this.timer);
+    this.timer = setInterval(() => this.advance(), delay);
+  }
+
+  private frames(): Partial<Record<ExpressionKey, number>> {
+    return Object.fromEntries(EXPRESSION_KEYS.map((key) => [key, this.expressions[key].frame]));
+  }
+
+  render(width: number): string[] {
+    const now = Date.now();
+    const opts = { width, rows: this.tui.terminal.rows, tick: this.tick, theme: this.theme(), expressions: this.frames(), oracleActivity };
+    const lines = panelLines(zenState.task, zenState.runs, now, isQuiet(), opts);
+    return lines.map((line) => truncateToWidth(line, width));
+  }
+
+  invalidate(): void {}
+
+  dispose(): void {
+    this.disposed = true;
+    clearInterval(this.timer);
+  }
+}
+
+function leaveZen(ctx: ExtensionContext): void {
+  if (!zenOn) return;
+  zenOn = false;
+  ctx.ui.setWorkingVisible(true);
+  ctx.ui.setWorkingIndicator();
+}
+
+/**
+ * Refresh the footer + widget to match the task on disk. Runs are merged into the
+ * retained set for the same task because each `orchestrate` call reports only its
+ * own agents: without retention the qa/reviewer call that follows the workers would
+ * evict their successes and the checklist would reset. A new task starts clean.
+ */
+export function applyStatus(ctx: ExtensionContext, root: string, configDir: string, runs: AgentRun[] = []): void {
+  const sessionId = ctx.sessionManager.getSessionId();
+  const task = isSubagentProcess() || minimized ? undefined : activeTask(root, configDir, sessionId);
+  const sameTask = zenState.task?.id === task?.id;
+  zenState = { task, runs: mergeRuns(sameTask ? zenState.runs : [], runs) };
+  ctx.ui.setStatus(STATUS_KEY, statusText(task, minimized));
+  const active = Boolean(task && !TERMINAL_STATES.includes(task.state));
+  if (!active) {
+    leaveZen(ctx);
+    ctx.ui.setWidget(STATUS_KEY, undefined);
+    return;
+  }
+  ctx.ui.setWorkingVisible(false);
+  ctx.ui.setWorkingIndicator({ frames: [] });
+  if (!zenOn) {
+    zenOn = true;
+    ctx.ui.setWidget(STATUS_KEY, (tui) => new ZenWidget(tui, () => ctx.ui.theme));
+  }
+}
+
+export function clearStatus(ctx: ExtensionContext): void {
+  leaveZen(ctx);
+  oracleActivity = undefined;
+  ctx.ui.setStatus(STATUS_KEY, undefined);
+  ctx.ui.setWidget(STATUS_KEY, undefined);
+}
+
+/** Register `alt+t`, the reveal-on-demand toggle for built-in tool rows. */
+export function registerRevealShortcut(pi: ExtensionAPI, configDir: string): void {
+  if (isSubagentProcess()) return;
+  pi.registerShortcut("alt+t", {
+    description: "bot-lobby: reveal or hide built-in tool rows",
+    handler: (ctx) => revealTools(ctx, configDir),
+  });
+  pi.registerShortcut(Key.ctrlShift("m"), {
+    description: "bot-lobby: minimize or restore the widget for this session",
+    handler: (ctx) => toggleMinimized(ctx, configDir),
+  });
+}
+
+function revealTools(ctx: ExtensionContext, configDir: string): void {
+  const quiet = toggleQuiet();
+  const expanded = ctx.ui.getToolsExpanded();
+  ctx.ui.setToolsExpanded(!expanded);
+  ctx.ui.setToolsExpanded(expanded);
+  applyStatus(ctx, detectProjectRoot(ctx.cwd, configDir), configDir, zenState.runs);
+  ctx.ui.notify(
+    quiet
+      ? "bot-lobby: tool rows hidden from now on — alt+t reveals them"
+      : "bot-lobby: tool rows shown from now on — ctrl+o expands, alt+t hides",
+    "info",
+  );
+}