@a-t-h-i/bot-lobby 0.4.0 → 0.5.1

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

@@ -0,0 +1,253 @@
+/**
+ * What the lobby narrates: an activity log of plain-words tool steps from the
+ * Master and every subagent, a single place for thoughts, and the conversation
+ * with the Master stripped of tool rows and thinking. Bounded ring buffers in
+ * one module-level store (like the zen widget state), so every event source can
+ * write without a reference to the lobby, and the lobby repaints on `version`.
+ */
+import type { AgentRun } from "../schemas/findings.ts";
+import { agentName } from "../pi/run-summary.ts";
+
+export type ActivityKind = "info" | "success" | "warning" | "error";
+
+export interface ActivityEntry {
+  id: number;
+  at: number;
+  /** Who acted: MASTER, DEV, DESIGN, QA, RESEARCH, QUICK FIX, PLANNER, LOBBY. */
+  source: string;
+  text: string;
+  kind: ActivityKind;
+  /** Still in flight; rendered with an ellipsis until it settles. */
+  pending: boolean;
+  /** Correlates a start with its end (a tool call id or a run id). */
+  key?: string;
+}
+
+export interface ThoughtEntry {
+  id: number;
+  at: number;
+  source: string;
+  text: string;
+  /** The Master's thought still streaming. */
+  live: boolean;
+}
+
+export type ChatRole = "you" | "oracle" | "note";
+
+export interface ChatEntry {
+  id: number;
+  at: number;
+  role: ChatRole;
+  text: string;
+}
+
+export const MAX_ACTIVITY = 400;
+export const MAX_THOUGHTS = 40;
+export const MAX_CHAT = 200;
+/** Longest thought kept; a streaming thought keeps its newest text. */
+export const MAX_THOUGHT_TEXT = 4000;
+
+function bounded<T>(list: T[], max: number): T[] {
+  return list.length > max ? list.slice(-max) : list;
+}
+
+export class LobbyFeed {
+  activity: ActivityEntry[] = [];
+  thoughts: ThoughtEntry[] = [];
+  chat: ChatEntry[] = [];
+  /** The oracle's reply while it streams; cleared when the message ends. */
+  reply = "";
+  version = 0;
+  private nextId = 1;
+  private readonly listeners = new Set<() => void>();
+  /** Last step reported per run, so repeated run updates log each step once. */
+  private readonly runSteps = new Map<string, string>();
+  private readonly runThoughts = new Map<string, string>();
+  private readonly runStatus = new Map<string, AgentRun["status"]>();
+
+  onChange(listener: () => void): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  private touch(): void {
+    this.version += 1;
+    for (const listener of this.listeners) listener();
+  }
+
+  /** Settle every pending entry of `source` (optionally only the one keyed `key`). */
+  private settle(source: string | undefined, key: string | undefined, kind?: ActivityKind): boolean {
+    let changed = false;
+    for (const entry of this.activity) {
+      if (!entry.pending) continue;
+      if (key !== undefined ? entry.key !== key : entry.source !== source) continue;
+      entry.pending = false;
+      if (kind) entry.kind = kind;
+      changed = true;
+    }
+    return changed;
+  }
+
+  /** A one-off entry that is already done (a receipt, a transition, a note). */
+  log(source: string, text: string, kind: ActivityKind = "info", at = Date.now()): void {
+    this.activity = bounded([...this.activity, { id: this.nextId++, at, source, text, kind, pending: false }], MAX_ACTIVITY);
+    this.touch();
+  }
+
+  /** Open an in-flight step; `key` lets `end` settle exactly this one. */
+  begin(source: string, text: string, key?: string, at = Date.now()): void {
+    this.activity = bounded([...this.activity, { id: this.nextId++, at, source, text, kind: "info", pending: true, ...(key ? { key } : {}) }], MAX_ACTIVITY);
+    this.touch();
+  }
+
+  /** Settle the step opened with `key`; an error marks it. */
+  end(key: string, isError = false): void {
+    if (this.settle(undefined, key, isError ? "error" : undefined)) this.touch();
+  }
+
+  /** The next step of an agent that reports one step at a time: the previous one settles. */
+  step(source: string, text: string, key: string, at = Date.now()): void {
+    this.settle(undefined, key);
+    this.begin(source, text, key, at);
+  }
+
+  /** Stream the Master's (or any source's) live thought. */
+  thinkDelta(source: string, delta: string, at = Date.now()): void {
+    const last = this.thoughts.at(-1);
+    if (last && last.live && last.source === source) {
+      const text = last.text + delta;
+      last.text = text.length > MAX_THOUGHT_TEXT ? text.slice(-MAX_THOUGHT_TEXT) : text;
+    } else {
+      this.thoughts = bounded([...this.thoughts, { id: this.nextId++, at, source, text: delta.slice(-MAX_THOUGHT_TEXT), live: true }], MAX_THOUGHTS);
+    }
+    this.touch();
+  }
+
+  /** Close the live thought of `source`, replacing it with the final text when given. */
+  thinkEnd(source: string, text?: string): void {
+    const last = [...this.thoughts].reverse().find((entry) => entry.source === source && entry.live);
+    if (!last) {
+      if (text?.trim()) this.thought(source, text);
+      return;
+    }
+    last.live = false;
+    if (text?.trim()) last.text = text.trim().slice(-MAX_THOUGHT_TEXT);
+    if (!last.text.trim()) this.thoughts = this.thoughts.filter((entry) => entry !== last);
+    this.touch();
+  }
+
+  /** A finished thought from an agent that reports whole thoughts (subagents). */
+  thought(source: string, text: string, at = Date.now()): void {
+    const body = text.trim();
+    if (!body) return;
+    this.thoughts = bounded([...this.thoughts, { id: this.nextId++, at, source, text: body.slice(-MAX_THOUGHT_TEXT), live: false }], MAX_THOUGHTS);
+    this.touch();
+  }
+
+  /** Stream the oracle's reply text as it arrives. */
+  replyDelta(delta: string): void {
+    this.reply = (this.reply + delta).slice(-MAX_THOUGHT_TEXT);
+    this.touch();
+  }
+
+  /** The streamed reply is over; `say` records the final message. */
+  replyEnd(): void {
+    if (!this.reply) return;
+    this.reply = "";
+    this.touch();
+  }
+
+  say(role: ChatRole, text: string, at = Date.now()): void {
+    const body = text.trim();
+    if (!body) return;
+    this.chat = bounded([...this.chat, { id: this.nextId++, at, role, text: body }], MAX_CHAT);
+    this.touch();
+  }
+
+  /** Replace the conversation (seeding from the session when the lobby first opens). */
+  seedChat(entries: ReadonlyArray<{ role: ChatRole; text: string; at?: number }>): void {
+    this.chat = bounded(entries.filter((entry) => entry.text.trim()).map((entry) => ({ id: this.nextId++, at: entry.at ?? 0, role: entry.role, text: entry.text.trim() })), MAX_CHAT);
+    this.touch();
+  }
+
+  /**
+   * Fold streamed subagent run updates into the log: each new plain-words step
+   * opens an entry (settling the previous one), each new thought lands in the
+   * thinking pane, and a finished run settles with its outcome.
+   */
+  runs(runs: readonly AgentRun[], at = Date.now()): void {
+    for (const run of runs) {
+      const source = agentName(run);
+      const key = run.runId;
+      const before = this.runStatus.get(key);
+      this.runStatus.set(key, run.status);
+      if (before === undefined) this.log(source, `started as ${run.role}`, "info", at);
+      if (run.step && this.runSteps.get(key) !== run.step) {
+        this.runSteps.set(key, run.step);
+        this.step(source, run.step, key, at);
+      }
+      if (run.thought && this.runThoughts.get(key) !== run.thought) {
+        this.runThoughts.set(key, run.thought);
+        this.thought(source, run.thought, at);
+      }
+      if (run.status !== "running" && before !== run.status) {
+        this.settle(undefined, key);
+        const kind: ActivityKind = run.status === "success" ? (run.wrappedUp ? "warning" : "success") : run.status === "cancelled" ? "warning" : "error";
+        this.log(source, `${run.role} ${run.status === "success" ? "finished" : run.status}${run.error ? ` — ${run.error.split("\n")[0]}` : ""}`, kind, at);
+      }
+    }
+  }
+
+  clear(): void {
+    this.activity = [];
+    this.thoughts = [];
+    this.chat = [];
+    this.reply = "";
+    this.runSteps.clear();
+    this.runThoughts.clear();
+    this.runStatus.clear();
+    this.touch();
+  }
+}
+
+/** The process-wide lobby feed; the Master session is the only writer that matters. */
+export const lobbyFeed = new LobbyFeed();
+
+/** The text parts of a message's content, joined; thinking and tool calls are dropped. */
+export function textOf(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .filter((part): part is { type: string; text: string } => typeof part === "object" && part !== null && (part as { type?: string }).type === "text" && typeof (part as { text?: unknown }).text === "string")
+    .map((part) => part.text)
+    .join("")
+    .trim();
+}
+
+/** 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 {
+  const body = text.trim();
+  if (!body) return undefined;
+  if (role === "assistant") return { role: "oracle", text: body };
+  const kickoff = /^A bot-lobby task is active: (\S+)\nTitle: (.*)/.exec(body);
+  if (kickoff) return { role: "note", text: `task ${kickoff[1]} started — ${kickoff[2]}` };
+  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 };
+}
+
+/** Session entries (`{ type: "message", message }`) as conversation entries, oldest first. */
+export function chatFromEntries(entries: readonly unknown[], max = MAX_CHAT): Array<{ role: ChatRole; text: string; at?: number }> {
+  const chat: Array<{ role: ChatRole; text: string; at?: number }> = [];
+  for (const entry of entries) {
+    const record = entry as { type?: string; timestamp?: string; message?: { role?: string; content?: unknown } };
+    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 } : {}) });
+  }
+  return chat.slice(-max);
+}