@a-t-h-i/bot-lobby 0.5.0 → 0.6.0

package/src/lobby/ask.ts

@@ -0,0 +1,226 @@
+/**
+ * The oracle puts the planning panel's questions to the user one at a time
+ * through the ask-user-question library (`@juicesharp/rpiv-ask-user-question`):
+ * a tabbed questionnaire with each seat's options, the recommended one first,
+ * and a free-text row on every question. The library only publishes a pi
+ * extension entry point, so its `ask_user_question` tool is captured by
+ * calling that entry with a `pi` whose `registerTool` keeps the definition
+ * instead of registering it; its `execute` then runs the real questionnaire.
+ * Without the library, pi's own select and input dialogs ask the same
+ * questions in the same order.
+ */
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { PanelQuestion } from "./planner.ts";
+
+/** The library's limits: at most 4 questions per questionnaire, 2-4 options each. */
+export const MAX_QUESTIONS = 4;
+export const MIN_OPTIONS = 2;
+export const MAX_OPTIONS = 4;
+const MAX_HEADER = 16;
+const MAX_LABEL = 60;
+/** Labels the library reserves for its own rows. */
+const RESERVED = new Set(["other", "type something.", "next"]);
+
+export interface AskOption {
+  label: string;
+  description: string;
+}
+
+export interface AskQuestion {
+  question: string;
+  header: string;
+  options: AskOption[];
+  multiSelect?: boolean;
+}
+
+export interface AskAnswer {
+  questionIndex: number;
+  question: string;
+  kind: "option" | "custom" | "multi";
+  answer: string | null;
+  selected?: string[];
+  notes?: string;
+}
+
+export interface AskResult {
+  answers: AskAnswer[];
+  cancelled: boolean;
+  globalNote?: string;
+}
+
+/** Puts up to `MAX_QUESTIONS` questions to the user and returns what they chose. */
+export type Asker = (questions: readonly AskQuestion[], ctx: ExtensionContext) => Promise<AskResult>;
+
+interface ToolLike {
+  execute(toolCallId: string, params: unknown, signal: AbortSignal | undefined, onUpdate: undefined, ctx: ExtensionContext): Promise<{ details?: unknown }>;
+}
+
+function clip(text: string, max: number): string {
+  const flat = text.replace(/\s+/g, " ").trim();
+  return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+}
+
+/** Filler options for a question the panel asked without any. */
+const DEFAULT_OPTIONS: readonly AskOption[] = [
+  { label: "Go with the recommendation", description: "Let the panel pick the option it recommends." },
+  { label: "Leave it open", description: "Skip this one for now; the panel may ask again." },
+];
+
+/** A panel question in the library's schema: seat as the chip, 2-4 unique, unreserved option labels. */
+export function toAskQuestion(question: PanelQuestion): AskQuestion {
+  const seen = new Set<string>();
+  const options: AskOption[] = [];
+  for (const option of question.options) {
+    let label = clip(option.label, MAX_LABEL);
+    if (!label || RESERVED.has(label.toLowerCase())) continue;
+    for (let n = 2; seen.has(label.toLowerCase()); n++) label = clip(`${option.label} (${n})`, MAX_LABEL);
+    seen.add(label.toLowerCase());
+    options.push({ label, description: option.description.trim() || label });
+    if (options.length === MAX_OPTIONS) break;
+  }
+  for (const filler of DEFAULT_OPTIONS) {
+    if (options.length >= MIN_OPTIONS) break;
+    if (!seen.has(filler.label.toLowerCase())) options.push({ ...filler });
+  }
+  return { question: question.text.trim(), header: clip(question.from, MAX_HEADER), options };
+}
+
+/** Split the round's questions into questionnaires of at most `MAX_QUESTIONS`, with unique question texts. */
+export function questionnaires(questions: readonly PanelQuestion[]): AskQuestion[][] {
+  const seen = new Set<string>();
+  const asked = questions.map((question) => {
+    const ask = toAskQuestion(question);
+    let text = ask.question;
+    for (let n = 2; seen.has(text.toLowerCase()); n++) text = `${ask.question} (${question.from}${n > 2 ? ` ${n}` : ""})`;
+    seen.add(text.toLowerCase());
+    return { ...ask, question: text };
+  });
+  const chunks: AskQuestion[][] = [];
+  for (let i = 0; i < asked.length; i += MAX_QUESTIONS) chunks.push(asked.slice(i, i + MAX_QUESTIONS));
+  return chunks;
+}
+
+function answerText(answer: AskAnswer | undefined): string | undefined {
+  if (!answer) return undefined;
+  if (answer.kind === "multi") return answer.selected && answer.selected.length > 0 ? answer.selected.join(", ") : undefined;
+  return answer.answer?.trim() || undefined;
+}
+
+/**
+ * The user's turn for the next round: every question with who asked it and
+ * the answer (`→ …`), their notes, and what they left unanswered. Undefined
+ * when nothing was answered.
+ */
+export function answerMessage(questions: readonly PanelQuestion[], results: readonly AskResult[]): string | undefined {
+  const lines: string[] = [];
+  const skipped: string[] = [];
+  const notes: string[] = [];
+  let answered = 0;
+  results.forEach((result, chunk) => {
+    if (result.globalNote?.trim()) notes.push(result.globalNote.trim());
+    const offset = chunk * MAX_QUESTIONS;
+    for (let i = 0; i < MAX_QUESTIONS; i++) {
+      const question = questions[offset + i];
+      if (!question) break;
+      const answer = result.answers.find((entry) => entry.questionIndex === i);
+      const text = answerText(answer);
+      const label = `${offset + i + 1}. [${question.from}] ${question.text.replace(/\s+/g, " ").trim()}`;
+      if (!text) {
+        skipped.push(label);
+        continue;
+      }
+      answered += 1;
+      lines.push(`${label}\n   → ${text}${answer?.kind === "custom" ? " (in my words)" : ""}`);
+      if (answer?.notes?.trim()) lines.push(`   note: ${answer.notes.trim()}`);
+    }
+  });
+  if (answered === 0 && notes.length === 0) return undefined;
+  return [
+    "Answers to the panel's questions:",
+    ...lines,
+    ...(notes.length > 0 ? ["", `Note: ${notes.join(" ")}`] : []),
+    ...(skipped.length > 0 ? ["", "Not answered this round:", ...skipped] : []),
+  ].join("\n");
+}
+
+/**
+ * Capture the library's tool through its public extension entry: the entry
+ * registers the tool on the `pi` it is given, so a `pi` whose `registerTool`
+ * keeps the definition (and whose `on` ignores the library's own tool-list
+ * reconciler) yields it without touching the session's tools. Undefined when
+ * the library is missing or registers nothing.
+ */
+/**
+ * The library ships TypeScript sources; a non-literal specifier keeps them out
+ * of this package's typecheck (they are compiled by pi's loader at runtime).
+ */
+const ASK_LIBRARY: string = "@juicesharp/rpiv-ask-user-question";
+
+export async function loadAskTool(pi: ExtensionAPI, load: () => Promise<unknown> = () => import(ASK_LIBRARY)): Promise<ToolLike | undefined> {
+  try {
+    const module = (await load()) as { default?: (pi: ExtensionAPI) => void };
+    if (typeof module.default !== "function") return undefined;
+    let captured: ToolLike | undefined;
+    const capture = new Proxy(pi, {
+      get(target, property, receiver) {
+        if (property === "registerTool") return (tool: ToolLike & { name?: string }) => {
+          if (tool.name === "ask_user_question") captured = tool;
+        };
+        if (property === "on") return () => () => {};
+        return Reflect.get(target, property, receiver);
+      },
+    });
+    module.default(capture);
+    return captured;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Run one questionnaire through the captured tool. */
+export function toolAsker(tool: ToolLike): Asker {
+  return async (questions, ctx) => {
+    const result = await tool.execute(`bot-lobby-panel-${Date.now().toString(36)}`, { questions }, undefined, undefined, ctx);
+    const details = result.details as Partial<AskResult> | undefined;
+    return { answers: details?.answers ?? [], cancelled: details?.cancelled !== false, ...(details?.globalNote ? { globalNote: details.globalNote } : {}) };
+  };
+}
+
+const TYPE_ANSWER = "Type an answer…";
+const SKIP = "Skip";
+
+/** The same questions through pi's built-in dialogs: pick an option, type an answer, or skip; esc stops. */
+export function dialogAsker(): Asker {
+  return async (questions, ctx) => {
+    const answers: AskAnswer[] = [];
+    for (const [index, question] of questions.entries()) {
+      const choices = [...question.options.map((option) => option.label), TYPE_ANSWER, SKIP];
+      const title = `${question.header} · ${index + 1}/${questions.length}\n\n${question.question}`;
+      const choice = await ctx.ui.select(title, choices);
+      if (choice === undefined) return { answers, cancelled: true };
+      if (choice === SKIP) continue;
+      if (choice === TYPE_ANSWER) {
+        const typed = await ctx.ui.input(question.question, "your answer");
+        if (typed === undefined) return { answers, cancelled: true };
+        if (typed.trim()) answers.push({ questionIndex: index, question: question.question, kind: "custom", answer: typed.trim() });
+        continue;
+      }
+      answers.push({ questionIndex: index, question: question.question, kind: "option", answer: choice });
+    }
+    return { answers, cancelled: false };
+  };
+}
+
+/**
+ * Put every question to the user, one questionnaire after another. Stopping
+ * a questionnaire (esc) stops the rest; what was answered before it is kept.
+ */
+export async function askPanel(questions: readonly PanelQuestion[], ask: Asker, ctx: ExtensionContext): Promise<{ results: AskResult[]; stopped: boolean }> {
+  const results: AskResult[] = [];
+  for (const chunk of questionnaires(questions)) {
+    const result = await ask(chunk, ctx);
+    if (result.cancelled) return { results, stopped: true };
+    results.push(result);
+  }
+  return { results, stopped: false };
+}

package/src/lobby/feed.ts

@@ -225,15 +225,19 @@ export function textOf(content: unknown): string {
 }
 
 /** The long kickoff message bot-lobby sends reads as a short note in the conversation. */
-export function chatText(role: "user" | "assistant", text: string): { role: ChatRole; text: string } | undefined {
+export function chatText(role: "user" | "assistant", text: string): Array<{ role: ChatRole; text: string }> {
   const body = text.trim();
-  if (!body) return undefined;
-  if (role === "assistant") return { role: "oracle", text: body };
+  if (!body) return [];
+  if (role === "assistant") return [{ role: "oracle", text: body }];
+  // bot-lobby's kickoff: the task starting, then what the user asked for, in their words.
   const kickoff = /^A bot-lobby task is active: (\S+)\nTitle: (.*)/.exec(body);
-  if (kickoff) return { role: "note", text: `task ${kickoff[1]} started — ${kickoff[2]}` };
+  if (kickoff) {
+    const request = /\nRequest: ([\s\S]*?)(?:\nState: |$)/.exec(body)?.[1]?.trim();
+    return [{ role: "note", text: `task started · ${kickoff[2]}` }, ...(request ? [{ role: "you" as const, text: request }] : [])];
+  }
   const comment = /^The user left (?:a comment|\d+ comments) on (the approved plan|the proposal) of (\S+) from the lobby:/.exec(body);
-  if (comment) return { role: "note", text: `plan comment sent to the oracle for ${comment[2]}` };
-  return { role: "you", text: body };
+  if (comment) return [{ role: "note", text: `your comment on ${comment[1]} went to the oracle` }];
+  return [{ role: "you", text: body }];
 }
 
 /** Session entries (`{ type: "message", message }`) as conversation entries, oldest first. */
@@ -244,10 +248,62 @@ export function chatFromEntries(entries: readonly unknown[], max = MAX_CHAT): Ar
     if (record?.type !== "message") continue;
     const role = record.message?.role;
     if (role !== "user" && role !== "assistant") continue;
-    const line = chatText(role, textOf(record.message?.content));
-    if (!line) continue;
     const at = record.timestamp ? Date.parse(record.timestamp) : undefined;
-    chat.push({ ...line, ...(at !== undefined && Number.isFinite(at) ? { at } : {}) });
+    for (const line of chatText(role, textOf(record.message?.content))) chat.push({ ...line, ...(at !== undefined && Number.isFinite(at) ? { at } : {}) });
   }
   return chat.slice(-max);
 }
+
+/** The parts of pi's agent events the lobby narrates; the same shape in process and over RPC. */
+export interface AgentEventLike {
+  type: string;
+  toolName?: string;
+  args?: unknown;
+  toolCallId?: string;
+  isError?: boolean;
+  assistantMessageEvent?: { type: string; delta?: string; content?: string };
+  message?: { role?: string; content?: unknown; stopReason?: string; errorMessage?: string };
+}
+
+/**
+ * One of a Master's agent events into a feed: tool calls become plain-words
+ * activity, thinking goes to the thinking pane, the reply streams, and
+ * finished messages join the conversation (a failed turn says so there too).
+ */
+export function narrateEvent(feed: LobbyFeed, event: AgentEventLike, describe: (toolName: string, args: unknown) => string): void {
+  switch (event.type) {
+    case "tool_execution_start":
+      feed.begin("MASTER", describe(event.toolName ?? "tool", event.args), event.toolCallId);
+      return;
+    case "tool_execution_end":
+      if (event.toolCallId) feed.end(event.toolCallId, event.isError === true);
+      return;
+    case "message_update": {
+      const update = event.assistantMessageEvent;
+      if (update?.type === "thinking_delta" && update.delta) feed.thinkDelta("MASTER", update.delta);
+      else if (update?.type === "thinking_end") feed.thinkEnd("MASTER", update.content);
+      else if (update?.type === "text_delta" && update.delta) feed.replyDelta(update.delta);
+      return;
+    }
+    case "message_end": {
+      const message = event.message ?? {};
+      if (message.role === "assistant") {
+        feed.replyEnd();
+        feed.thinkEnd("MASTER");
+        if (message.stopReason === "error") {
+          const error = (message.errorMessage ?? "the model call failed").split("\n")[0]!;
+          feed.say("note", `✗ the oracle's turn failed: ${error}`);
+          feed.log("MASTER", `turn failed — ${error}`, "error");
+        }
+      }
+      if (message.role !== "user" && message.role !== "assistant") return;
+      for (const line of chatText(message.role, textOf(message.content))) feed.say(line.role, line.text);
+      return;
+    }
+    case "agent_end":
+      feed.replyEnd();
+      return;
+    default:
+      return;
+  }
+}

package/src/lobby/keys.ts

@@ -0,0 +1,55 @@
+/**
+ * The lobby's shortcuts in one table: every action has a default key, a line
+ * for the help overlay, and can be rebound under `lobby.keys` in the config
+ * (`{ "toggleThinking": "alt+t" }`). They work in typing and browsing mode
+ * alike, so each default is a key that never types a character.
+ */
+import { matchesKey, type KeyId } from "@earendil-works/pi-tui";
+
+export const LOBBY_ACTIONS = {
+  hide: { key: "alt+l", help: "hide the lobby (back to pi)" },
+  help: { key: "alt+h", help: "show or hide these keys" },
+  settings: { key: "alt+s", help: "bot-lobby settings: each agent's model and thinking, the lobby" },
+  search: { key: "ctrl+f", help: "search the current tab" },
+  savePlan: { key: "ctrl+s", help: "save the plan being made in the Plan tab to the pending tasks" },
+  sessions: { key: "alt+o", help: "switch session: this window, background sessions, other terminals" },
+  newSession: { key: "alt+n", help: "start a task in a new session, named after it" },
+  toggleAuto: { key: "alt+g", help: "auto mode: the oracle drives the task to completion without asking" },
+  nextTab: { key: "tab", help: "next tab" },
+  prevTab: { key: "shift+tab", help: "previous tab" },
+  toggleScene: { key: "alt+z", help: "show or hide the oracle and agent animations" },
+  toggleConversation: { key: "alt+c", help: "show or hide the conversation" },
+  toggleActivity: { key: "alt+a", help: "show or hide the activity log" },
+  toggleThinking: { key: "alt+k", help: "show or hide thinking" },
+  scrollUp: { key: "pageUp", help: "scroll up a page" },
+  scrollDown: { key: "pageDown", help: "scroll down a page" },
+} as const;
+
+export type LobbyAction = keyof typeof LOBBY_ACTIONS;
+
+export type KeyMap = Record<LobbyAction, string>;
+
+/** Defaults with the config's overrides on top; unknown action names are ignored. */
+export function keyMap(overrides: Readonly<Record<string, string>> = {}): KeyMap {
+  const map = Object.fromEntries(Object.entries(LOBBY_ACTIONS).map(([action, entry]) => [action, entry.key])) as KeyMap;
+  for (const [action, key] of Object.entries(overrides)) {
+    if (action in map && key.trim()) map[action as LobbyAction] = key.trim().toLowerCase();
+  }
+  return map;
+}
+
+/** The action `data` triggers under `map`, if any. */
+export function actionFor(data: string, map: KeyMap): LobbyAction | undefined {
+  for (const action of Object.keys(map) as LobbyAction[]) {
+    if (matchesKey(data, map[action] as KeyId)) return action;
+  }
+  return undefined;
+}
+
+/** `alt+k` reads `Alt+K` in hints and help. */
+export function keyLabel(key: string): string {
+  return key
+    .split("+")
+    .map((part) => (part.length === 1 ? part.toUpperCase() : part[0]!.toUpperCase() + part.slice(1)))
+    .join("+");
+}

package/src/lobby/layout.ts

@@ -20,13 +20,18 @@ export type LobbyColor =
   | "borderMuted"
   | "toolTitle"
   | "mdHeading"
-  | "mdCode";
+  | "mdCode"
+  | "userMessageText";
 
 export interface LobbyTheme {
   fg(color: LobbyColor, text: string): string;
   bold(text: string): string;
   italic?(text: string): string;
-  bg?(color: "selectedBg", text: string): string;
+  bg?(color: "selectedBg" | "searchMatchBg" | "userMessageBg", text: string): string;
+  /** Render Markdown to styled lines; plain wrapping without it (tests). */
+  markdown?(text: string, width: number): string[];
+  /** Strike text through (an abandoned task's title); plain without it (tests). */
+  strike?(text: string): string;
 }
 
 /** Paint only when a theme is present; tests without one get plain text. */
@@ -42,10 +47,22 @@ export function italic(theme: LobbyTheme | undefined, text: string): string {
   return theme?.italic && text ? theme.italic(text) : text;
 }
 
+export function strike(theme: LobbyTheme | undefined, text: string): string {
+  return theme?.strike && text ? theme.strike(text) : text;
+}
+
+/** `left` and `right` on one line of exactly `width` columns: the left side gives way first. */
+export function spread(left: string, right: string, width: number): string {
+  if (!right) return fit(left, width);
+  const room = width - visibleWidth(right) - 1;
+  if (room < 4) return fit(left, width);
+  return `${fit(left, room)} ${right}`;
+}
+
 /** Exactly `width` columns: truncated with an ellipsis, or padded with spaces. */
 export function fit(text: string, width: number): string {
   if (width <= 0) return "";
-  const cut = visibleWidth(text) > width ? truncateToWidth(text, width) : text;
+  const cut = visibleWidth(text) > width ? truncateToWidth(text, width, "…") : text;
   const pad = width - visibleWidth(cut);
   return pad > 0 ? `${cut}${" ".repeat(pad)}` : cut;
 }
@@ -165,10 +182,197 @@ export function spinner(tick: number): string {
   return SPINNER[((tick % SPINNER.length) + SPINNER.length) % SPINNER.length]!;
 }
 
-/** Light Markdown for plans and reports: headings bold without their `#`, everything else wrapped as written. */
+/** Markdown for plans, reports and replies: the theme's renderer, or headings bold without their `#` and the rest wrapped. */
 export function markdownLines(text: string, width: number, theme?: LobbyTheme): string[] {
+  if (theme?.markdown) return theme.markdown(text, width);
   return text.split("\n").flatMap((line) => {
     const heading = /^#{1,6}\s+(.*)$/.exec(line);
     return wrap(heading ? bold(theme, paint(theme, "mdHeading", heading[1]!)) : line, width);
   });
 }
+
+/** Markdown behind a hanging lead (`oracle ▸ `): the first line carries the lead, the rest align under it. */
+export function markdownHanging(lead: string, text: string, width: number, theme?: LobbyTheme): string[] {
+  const indent = visibleWidth(lead);
+  const body = markdownLines(text, Math.max(1, width - indent), theme);
+  if (body.length === 0) return [lead];
+  return body.map((line, index) => (index === 0 ? `${lead}${line}` : line ? `${" ".repeat(indent)}${line}` : ""));
+}
+
+export interface BoxOptions {
+  title?: string;
+  /** Muted text at the right end of the top border. */
+  right?: string;
+  /** The box that has the keyboard: its border takes the accent colour. */
+  focused?: boolean;
+  theme?: LobbyTheme;
+  /** Content longer than the box: `total` lines, the first shown at `start`; drawn as a thumb on the right border. */
+  scroll?: { total: number; start: number };
+}
+
+/** A scrollable pane as a render laid it out: its box in body cells, and its content against its rows. */
+export interface PaneBox {
+  top: number;
+  left: number;
+  width: number;
+  height: number;
+  /** Lines of content, and rows showing them at once. */
+  total: number;
+  rows: number;
+}
+
+/** Scrollable panes by name, filled in by a tab's render so the lobby can clamp offsets and route the wheel. */
+export type PaneLayout = Map<string, PaneBox>;
+
+/** Record a pane that sits at `top`/`left` in the body, `width` × `height`, showing `total` lines. */
+export function notePane(panes: PaneLayout | undefined, name: string, top: number, left: number, width: number, height: number, total: number): void {
+  panes?.set(name, { top, left, width, height, total, rows: Math.max(0, height - 2) });
+}
+
+/** First line of a top-anchored pane scrolled `offset` lines down, stopping when its last line shows. */
+export function detailWindow(total: number, rows: number, offset: number): number {
+  return Math.max(0, Math.min(offset, total - Math.max(1, rows)));
+}
+
+/** `12–40/96`: the lines a pane shows out of all it holds. */
+export function position(start: number, rows: number, total: number): string {
+  return `${start + 1}–${Math.min(total, start + rows)}/${total}`;
+}
+
+/** The rows of a `rows`-tall track that the thumb covers, or undefined when everything fits. */
+export function scrollThumb(total: number, rows: number, start: number): { from: number; to: number } | undefined {
+  if (rows <= 0 || total <= rows) return undefined;
+  const size = Math.max(1, Math.round((rows * rows) / total));
+  const max = total - rows;
+  const from = Math.round((Math.min(max, Math.max(0, start)) / max) * (rows - size));
+  return { from, to: from + size };
+}
+
+/**
+ * A rounded panel exactly `width` × `height`: the title set into the top
+ * border, `content` inside with one column of padding, extra lines cut and
+ * missing ones blank. Below 4 columns or 2 rows it degrades to plain lines.
+ */
+export function box(width: number, height: number, content: readonly string[], options: BoxOptions = {}): string[] {
+  if (height <= 0) return [];
+  if (width < 4 || height < 2) return fill(content, height, Math.max(0, width));
+  const { theme, focused } = options;
+  const edge = (text: string) => paint(theme, focused ? "borderAccent" : "borderMuted", text);
+  const inner = width - 4;
+  const title = options.title ? ` ${options.title} ` : "";
+  const right = options.right ? ` ${options.right} ` : "";
+  let room = width - 2 - visibleWidth(title) - visibleWidth(right);
+  const shownRight = room >= 1 ? right : "";
+  room = width - 2 - visibleWidth(title) - visibleWidth(shownRight);
+  const titled = room >= 1 ? title : fit(title, Math.max(0, width - 3));
+  const fillWidth = Math.max(0, width - 2 - visibleWidth(titled) - visibleWidth(shownRight));
+  const paintedTitle = titled ? bold(theme, paint(theme, focused ? "accent" : "text", titled)) : "";
+  const top = `${edge("╭")}${paintedTitle}${edge("─".repeat(fillWidth))}${shownRight ? paint(theme, "dim", shownRight) : ""}${edge("╮")}`;
+  const thumb = options.scroll ? scrollThumb(options.scroll.total, height - 2, options.scroll.start) : undefined;
+  const rightEdge = (row: number) => (thumb && row >= thumb.from && row < thumb.to ? paint(theme, focused ? "accent" : "muted", "┃") : edge("│"));
+  const rows = fill(content, height - 2).map((line, row) => `${edge("│")} ${fit(line, inner)} ${rightEdge(row)}`);
+  return [top, ...rows, `${edge("╰")}${edge("─".repeat(width - 2))}${edge("╯")}`];
+}
+
+/** Lay boxes out side by side, each already exactly its width and the same height. */
+export function beside(panes: ReadonlyArray<readonly string[]>, gap = " "): string[] {
+  const height = Math.max(0, ...panes.map((pane) => pane.length));
+  return Array.from({ length: height }, (_, row) => panes.map((pane) => pane[row] ?? "").join(gap));
+}
+
+/** Escape sequences (CSI, OSC, APC) that take no columns. */
+const ESCAPE = /\x1b(?:\[[0-9;?]*[ -\/]*[@-~]|\][^\x07\x1b]*(?:\x07|\x1b\\)|_[^\x07\x1b]*(?:\x07|\x1b\\))/y;
+
+/**
+ * Mark every case-insensitive occurrence of `query` in a styled line with
+ * reverse video. Escape sequences are skipped when matching and kept intact,
+ * and reverse video is switched off (not reset) so the line's own colours
+ * carry on after each match.
+ */
+export function highlight(line: string, query: string): string {
+  const needle = query.trim().toLowerCase();
+  if (!needle) return line;
+  // Visible characters with their raw offsets.
+  const chars: Array<{ ch: string; at: number }> = [];
+  for (let i = 0; i < line.length; ) {
+    ESCAPE.lastIndex = i;
+    const escape = ESCAPE.exec(line);
+    if (escape) {
+      i += escape[0].length;
+      continue;
+    }
+    const point = line.codePointAt(i)!;
+    const ch = String.fromCodePoint(point);
+    chars.push({ ch, at: i });
+    i += ch.length;
+  }
+  const visible = chars.map((entry) => entry.ch).join("").toLowerCase();
+  const starts: Array<[number, number]> = [];
+  for (let from = visible.indexOf(needle); from >= 0; from = visible.indexOf(needle, from + needle.length)) starts.push([from, from + needle.length]);
+  if (starts.length === 0) return line;
+  // Map visible string offsets back to char indexes (they differ only for astral characters).
+  const charAt: number[] = [];
+  chars.forEach((entry, index) => {
+    for (let k = 0; k < entry.ch.length; k++) charAt.push(index);
+  });
+  let out = "";
+  let cursor = 0;
+  for (const [start, end] of starts) {
+    const from = chars[charAt[start]!]!.at;
+    const lastChar = chars[charAt[end - 1]!]!;
+    const to = lastChar.at + lastChar.ch.length;
+    out += `${line.slice(cursor, from)}\x1b[7m${line.slice(from, to)}\x1b[27m`;
+    cursor = to;
+  }
+  return out + line.slice(cursor);
+}
+
+const EIGHTHS = ["", "▏", "▎", "▍", "▌", "▋", "▊", "▉"];
+
+/** A horizontal bar `value / max` of `width` cells, with eighth-cell precision at its end. */
+export function bar(value: number, max: number, width: number): string {
+  if (width <= 0 || !Number.isFinite(value) || !Number.isFinite(max) || max <= 0 || value <= 0) return "";
+  const cells = Math.min(width, (value / max) * width);
+  const whole = Math.floor(cells);
+  const part = EIGHTHS[Math.round((cells - whole) * 8)] ?? "";
+  // A non-zero value always shows at least a sliver.
+  return `${"█".repeat(whole)}${part}` || "▏";
+}
+
+/** A meter `fraction` full: filled cells over a dim track, exactly `width` wide. */
+export function meter(fraction: number, width: number, fillPaint: (text: string) => string, trackPaint: (text: string) => string): string {
+  if (width <= 0) return "";
+  const safe = Number.isFinite(fraction) ? Math.min(1, Math.max(0, fraction)) : 0;
+  const filled = Math.round(safe * width);
+  return `${fillPaint("━".repeat(filled))}${trackPaint("─".repeat(width - filled))}`;
+}
+
+const SPARKS = ["▁", "▂", "▃", "▄", "▅", "▆", "▇", "█"];
+
+/** A sparkline of the last `width` values, scaled between their min and max. */
+export function sparkline(values: readonly number[], width: number): string {
+  const shown = values.filter((value) => Number.isFinite(value)).slice(-Math.max(0, width));
+  if (shown.length === 0) return "";
+  const low = Math.min(...shown);
+  const high = Math.max(...shown);
+  const span = high - low;
+  return shown.map((value) => SPARKS[span === 0 ? 3 : Math.min(7, Math.floor(((value - low) / span) * 8))]).join("");
+}
+
+/**
+ * A part-to-whole bar: each segment's share of `width` cells in its own
+ * colour, rounded so the segments always fill the bar exactly.
+ */
+export function stackedBar(segments: ReadonlyArray<{ value: number; paint: (text: string) => string }>, width: number): string {
+  const total = segments.reduce((sum, segment) => sum + Math.max(0, segment.value), 0);
+  if (width <= 0 || total <= 0) return "";
+  let used = 0;
+  let acc = 0;
+  return segments.map((segment) => {
+    acc += Math.max(0, segment.value);
+    const end = Math.round((acc / total) * width);
+    const cells = end - used;
+    used = end;
+    return cells > 0 ? segment.paint("█".repeat(cells)) : "";
+  }).join("");
+}

package/src/lobby/markdown.ts

@@ -0,0 +1,48 @@
+/**
+ * Markdown for the lobby: pi's own renderer (headings, emphasis, lists, code
+ * with syntax highlighting, quotes, tables) under the session's theme, with
+ * heading hashes dropped for a cleaner read. Renders are cached per theme,
+ * width and text, since the lobby repaints several times a second.
+ */
+import { getMarkdownTheme } from "@earendil-works/pi-coding-agent";
+import { Markdown, stripTerminalSequences, type MarkdownTheme } from "@earendil-works/pi-tui";
+
+export type MarkdownRenderer = (text: string, width: number) => string[];
+
+const CACHE_LIMIT = 96;
+
+/** A heading line as pi renders it: optional styling, then `#`…`######` and a space. */
+const HEADING_HASHES = /^((?:\x1b\[[0-9;]*m)*)#{1,6} ((?:\x1b\[[0-9;]*m)*)/;
+
+/** Drop the `### ` pi keeps in front of headings, and make them bold. */
+export function tidyHeading(line: string, bold: (text: string) => string): string {
+  if (!/^#{1,6} /.test(stripTerminalSequences(line))) return line;
+  const body = line.replace(HEADING_HASHES, "$1$2");
+  return bold(body.trimEnd());
+}
+
+/**
+ * A renderer bound to a theme provider. `theme()` is read on every call, so a
+ * theme switch re-renders instead of serving stale colours from the cache.
+ */
+export function createMarkdownRenderer(theme: () => MarkdownTheme = getMarkdownTheme): MarkdownRenderer {
+  const caches = new WeakMap<object, Map<string, string[]>>();
+  return (text, width) => {
+    const current = theme();
+    let cache = caches.get(current);
+    if (!cache) {
+      cache = new Map();
+      caches.set(current, cache);
+    }
+    const key = `${width}\0${text}`;
+    const hit = cache.get(key);
+    if (hit) return hit;
+    const lines = new Markdown(text, 0, 0, current).render(Math.max(1, width)).map((line) => tidyHeading(line.trimEnd(), current.bold));
+    // Drop the blank lines pi pads the render with at either end.
+    while (lines.length > 0 && !lines[0]!.trim()) lines.shift();
+    while (lines.length > 0 && !lines.at(-1)!.trim()) lines.pop();
+    cache.set(key, lines);
+    if (cache.size > CACHE_LIMIT) cache.delete(cache.keys().next().value!);
+    return lines;
+  };
+}