@a-t-h-i/bot-lobby 0.6.12 → 0.6.13

package/src/webui/dev/fixtures.ts

@@ -0,0 +1,180 @@
+/**
+ * Fixture sets for `npm run web:dev`: one JSON file per scenario under
+ * `webui/fixtures/`. Dev-only; the production server never reads these.
+ * Unknown scenario names fall back to `full`.
+ */
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { ChatRole } from "../../lobby/feed.ts";
+import type { PromptKind } from "../../lobby/prompt-hub.ts";
+import type { SnapshotTask } from "../protocol.ts";
+
+/** Every scenario the mock serves; `?scenario=` picks one. */
+export const SCENARIOS = [
+  "full",
+  "empty",
+  "loading",
+  "error",
+  "reconnecting",
+  "question",
+  "questions3",
+  "answered-in-terminal",
+  "terminal-dialog",
+  "issues",
+] as const;
+
+export type ScenarioName = (typeof SCENARIOS)[number];
+
+export interface FixturePrompt {
+  kind: PromptKind;
+  from: string;
+  payload: unknown;
+}
+
+export interface FixtureSettled extends FixturePrompt {
+  answer: unknown;
+}
+
+/** One scenario file: what every protocol call answers from. */
+export interface ScenarioFixture {
+  status: {
+    workspace: { name: string; branch?: string };
+    sessionId: string;
+    sessionName: string;
+    busy: boolean;
+    terminalDialog: boolean;
+    issuesEnabled: boolean;
+  };
+  zen: { task?: Partial<SnapshotTask> & { id: string; title: string; state: string; plan?: string }; runs: unknown[] };
+  feed: {
+    chat: Array<{ role: ChatRole; text: string }>;
+    activity: Array<{ source: string; text: string; kind: "info" | "success" | "warning" | "error"; pending: boolean }>;
+    thoughts: Array<{ source: string; text: string }>;
+    reply: string;
+    chatOlder: boolean;
+  };
+  history: Array<{ role: ChatRole; text: string }>;
+  prompts: FixturePrompt[];
+  settled: FixtureSettled[];
+  /** Streamed back (in deltas) after `lobby.send`. */
+  oracleReply: string;
+  /** The Settings page's mock: a partial config merged over the defaults, and the models Pi offers. */
+  settings?: { config?: Record<string, unknown>; models?: Array<{ id: string; label: string; thinkingLevels: string[] }> };
+  /** Opened through `promptHub` shortly after a send, if any. */
+  questionAfterSend: FixturePrompt | null;
+  /** Tasks backing `tasks.list` (absent means none). */
+  mockTasks?: Array<Record<string, unknown>>;
+  /** Saved plans backing `plans.start`/`plans.discard` and the pending rows. */
+  mockPlans?: Array<{ id: string; title: string; brief: string }>;
+  /** Archived tasks backing `tasks.archived`. */
+  mockArchived?: Array<Record<string, unknown>>;
+  /** Task ids with auto mode on. */
+  autoTasks?: string[];
+  /** Comments by task id for `tasks.comments`. */
+  taskComments?: Record<string, Array<Record<string, unknown>>>;
+  /** Background sessions for `sessions.list` (plain data, made live below). */
+  backgroundSessions?: Array<{ key: string; name: string; status: string; sessionId?: string; planId?: string; dialogs?: Array<Record<string, unknown>> }>;
+  /** Live sessions in other terminals for `sessions.list`. */
+  liveSessions?: Array<{ sessionId: string; pid: number; name?: string; taskId?: string; mode: string }>;
+  /** The planning session for the `planner.*` calls (absent means none started). */
+  mockPlanner?: {
+    seats: string[];
+    members: Array<Record<string, unknown>>;
+    messages: Array<Record<string, unknown>>;
+    draft?: string;
+    questions: Array<Record<string, unknown>>;
+    notes: Array<Record<string, unknown>>;
+    round: number;
+    retryable: boolean;
+  };
+  /** Quick-fix jobs for the `quickfix.*` calls, oldest first (absent means none). */
+  mockQuickfix?: Array<Record<string, unknown>>;
+  /** Metric records for `metrics.get` (absent means none). */
+  mockMetrics?: Array<Record<string, unknown>>;
+  /** Classifier records for `metrics.get` (absent means none). */
+  mockClassifierMetrics?: Array<Record<string, unknown>>;
+  /** Knowledge files for `knowledge.files` (absent means none). */
+  mockKnowledge?: Array<{ agent: string; file: string; label: string; chars: number; over: boolean; notes: number }>;
+  /** One open knowledge file for `knowledge.open` (absent means an empty file). */
+  mockKnowledgeView?: { agent: string; file: string; label: string; chars: number; over: boolean; notes: number; content: string; entries: Array<Record<string, unknown>>; attached: Array<Record<string, unknown>>; detached: Array<Record<string, unknown>> };
+  /** Excalidraw sessions for `excalidraw.list` (masked links only; absent means none). */
+  mockExcalidraw?: Array<{ id: string; name: string; masked: string; agents: string[]; contribute: boolean; addedAt: string }>;
+  /** The full link `excalidraw.reveal` returns (absent means none). */
+  mockExcalidrawLink?: string;
+  /** Open pull requests for the `git.*` calls, each with its detail fields (absent means none). */
+  mockPulls?: Array<Record<string, unknown>>;
+  /** Saved reviews of those pull requests, by number. */
+  mockReviews?: Array<Record<string, unknown>>;
+  /** Jev's reads of those pull requests, by number. */
+  mockReads?: Array<Record<string, unknown>>;
+  /** Open issues for the `issues.*` calls, each with its detail fields (absent means none). */
+  mockIssues?: Array<Record<string, unknown>>;
+}
+
+/** Whether `value` names a scenario. */
+export function isScenario(value: string): value is ScenarioName {
+  return (SCENARIOS as readonly string[]).includes(value);
+}
+
+/** The scenario to serve; unknown or missing names mean `full`. */
+export function resolveScenario(value: string | undefined): ScenarioName {
+  return value !== undefined && isScenario(value) ? value : "full";
+}
+
+/** Where `webui/fixtures/<name>.json` lives. */
+export function fixturePath(name: ScenarioName): string {
+  const root = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
+  return join(root, "webui", "fixtures", `${name}.json`);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function hasKeys(value: unknown, keys: readonly string[]): value is Record<string, unknown> {
+  return isRecord(value) && keys.every((key) => key in value);
+}
+
+/** The parsed file, or throws when it does not cover every protocol call. */
+export function loadScenario(name: string | undefined): ScenarioFixture {
+  const scenario = resolveScenario(name);
+  const parsed: unknown = JSON.parse(readFileSync(fixturePath(scenario), "utf8"));
+  if (!hasKeys(parsed, ["status", "zen", "feed", "history", "prompts", "oracleReply"])) {
+    throw new Error(`fixtures/${scenario}.json must cover status, zen, feed, history, prompts and oracleReply`);
+  }
+  if (!hasKeys(parsed.status, ["workspace", "sessionId", "sessionName", "busy", "terminalDialog", "issuesEnabled"])) {
+    throw new Error(`fixtures/${scenario}.json status must carry workspace, session, busy, terminalDialog and issuesEnabled`);
+  }
+  if (!hasKeys(parsed.zen, ["runs"]) || !hasKeys(parsed.feed, ["chat", "activity", "thoughts", "reply", "chatOlder"])) {
+    throw new Error(`fixtures/${scenario}.json zen/feed are missing their fields`);
+  }
+  if (!Array.isArray(parsed.history) || !Array.isArray(parsed.prompts) || typeof parsed.oracleReply !== "string") {
+    throw new Error(`fixtures/${scenario}.json history/prompts/oracleReply have the wrong shape`);
+  }
+  return {
+    ...(parsed as unknown as ScenarioFixture),
+    settled: Array.isArray(parsed.settled) ? (parsed.settled as ScenarioFixture["settled"]) : [],
+    questionAfterSend: isRecord(parsed.questionAfterSend) ? (parsed.questionAfterSend as unknown as FixturePrompt) : null,
+    taskComments: isRecord(parsed.taskComments) ? (parsed.taskComments as ScenarioFixture["taskComments"]) : {},
+    mockTasks: Array.isArray(parsed.mockTasks) ? (parsed.mockTasks as ScenarioFixture["mockTasks"]) : [],
+    mockPlans: Array.isArray(parsed.mockPlans) ? (parsed.mockPlans as ScenarioFixture["mockPlans"]) : [],
+    mockArchived: Array.isArray(parsed.mockArchived) ? (parsed.mockArchived as ScenarioFixture["mockArchived"]) : [],
+    autoTasks: Array.isArray(parsed.autoTasks) ? (parsed.autoTasks as string[]) : [],
+    backgroundSessions: Array.isArray(parsed.backgroundSessions) ? (parsed.backgroundSessions as ScenarioFixture["backgroundSessions"]) : [],
+    liveSessions: Array.isArray(parsed.liveSessions) ? (parsed.liveSessions as ScenarioFixture["liveSessions"]) : [],
+    mockPlanner: isRecord(parsed.mockPlanner) ? (parsed.mockPlanner as unknown as ScenarioFixture["mockPlanner"]) : undefined,
+    mockQuickfix: Array.isArray(parsed.mockQuickfix) ? (parsed.mockQuickfix as ScenarioFixture["mockQuickfix"]) : [],
+    mockMetrics: Array.isArray(parsed.mockMetrics) ? (parsed.mockMetrics as ScenarioFixture["mockMetrics"]) : [],
+    mockClassifierMetrics: Array.isArray(parsed.mockClassifierMetrics) ? (parsed.mockClassifierMetrics as ScenarioFixture["mockClassifierMetrics"]) : [],
+    mockKnowledge: Array.isArray(parsed.mockKnowledge) ? (parsed.mockKnowledge as ScenarioFixture["mockKnowledge"]) : [],
+    mockKnowledgeView: isRecord(parsed.mockKnowledgeView) ? (parsed.mockKnowledgeView as unknown as ScenarioFixture["mockKnowledgeView"]) : undefined,
+    mockExcalidraw: Array.isArray(parsed.mockExcalidraw) ? (parsed.mockExcalidraw as ScenarioFixture["mockExcalidraw"]) : [],
+    mockExcalidrawLink: typeof parsed.mockExcalidrawLink === "string" ? (parsed.mockExcalidrawLink as string) : undefined,
+    mockPulls: Array.isArray(parsed.mockPulls) ? (parsed.mockPulls as ScenarioFixture["mockPulls"]) : [],
+    mockReviews: Array.isArray(parsed.mockReviews) ? (parsed.mockReviews as ScenarioFixture["mockReviews"]) : [],
+    mockReads: Array.isArray(parsed.mockReads) ? (parsed.mockReads as ScenarioFixture["mockReads"]) : [],
+    mockIssues: Array.isArray(parsed.mockIssues) ? (parsed.mockIssues as ScenarioFixture["mockIssues"]) : [],
+    settings: isRecord(parsed.settings) ? (parsed.settings as ScenarioFixture["settings"]) : undefined,
+  };
+}

package/src/webui/dev/serve.ts

@@ -0,0 +1,54 @@
+/**
+ * `npm run web:dev`: the real loopback server with a fixture-backed service,
+ * so the page builds with no Pi. The scenario comes from `--scenario=<name>`
+ * or `WEB_SCENARIO` (default `full`); the printed link carries it as
+ * `?scenario=`. This is a dev CLI, so stdout is allowed here only — the
+ * production server still writes nothing. Rebuild with `npm run web:build`,
+ * then reload the page when `webui/dist` changes (the watcher says so).
+ */
+import { watch } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadConfig } from "../../state/project.ts";
+import { startWebServer } from "../server.ts";
+import { createFixtureService } from "./fake-service.ts";
+import { resolveScenario } from "./fixtures.ts";
+
+/** `--scenario=<name>` wins, then `WEB_SCENARIO`, then the default. */
+function argScenario(): string | undefined {
+  const found = process.argv.slice(2).find((arg) => arg.startsWith("--scenario="));
+  return found ? found.slice("--scenario=".length) : process.env.WEB_SCENARIO;
+}
+
+/** Config `lobby.web.port` (0 means any free port); an unreadable config means 0. */
+function configuredPort(): number {
+  try {
+    return loadConfig().lobby.web.port ?? 0;
+  } catch {
+    return 0;
+  }
+}
+
+/** The server link with the scenario in its query string. */
+function withScenario(link: string, scenario: string): string {
+  return link.replace("#", `?scenario=${scenario}#`);
+}
+
+/** Say when a rebuild lands, so the page gets reloaded; keep it to a line. */
+function watchDist(): void {
+  const dist = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "webui", "dist");
+  try {
+    watch(dist, () => {
+      console.log("webui/dist changed — reload the page (rebuild: npm run web:build)");
+    });
+  } catch {
+    console.log("webui/dist is missing — build it first: npm run web:build");
+  }
+}
+
+const scenario = resolveScenario(argScenario());
+const service = createFixtureService(scenario);
+const server = await startWebServer({ service, port: configuredPort() });
+console.log(`bot-lobby mock [${scenario}]: ${withScenario(server.link, scenario)}`);
+console.log("switch sets: WEB_SCENARIO=<name> npm run web:dev (or --scenario=<name>)");
+watchDist();

package/src/webui/events.ts

@@ -0,0 +1,207 @@
+/**
+ * `GET /api/events`, the page's server-sent event stream. Says `hello` with
+ * every topic's version on connect, then `changed {topic,version}` (at most
+ * one per topic per 40 ms), `feed` deltas (entries after the client's last
+ * ids, passed as query params) and the streaming `reply` text. At most 8
+ * streams; the oldest closes when a ninth opens. A `:ping` every 15 s keeps
+ * proxies and phones from closing an idle stream.
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { lobbyTopics, type LobbyTopic } from "../lobby/topics.ts";
+import type { LobbyService } from "../lobby/service.ts";
+import type { StreamEvent } from "./protocol.ts";
+import { onNotice, watchFeed, type Notice } from "./notices.ts";
+
+/** Concurrent streams; the oldest closes when one more opens. */
+export const MAX_STREAMS = 8;
+/** Topic changes share one message per topic per this many ms (the lobby's frame). */
+export const COALESCE_MS = 40;
+/** How often an idle stream says it is alive. */
+export const HEARTBEAT_MS = 15_000;
+
+interface Stream {
+  res: ServerResponse;
+  beat: ReturnType<typeof setInterval>;
+  activityAfter: number;
+  thoughtsAfter: number;
+  chatAfter: number;
+}
+
+function frame(event: StreamEvent): string {
+  return `data: ${JSON.stringify(event)}\n\n`;
+}
+
+function idOf(entry: unknown): number {
+  return typeof (entry as { id?: unknown }).id === "number" ? ((entry as { id: number }).id as number) : 0;
+}
+
+/** The event stream hub for one server; re-attached when the service changes. */
+export class EventHub {
+  private streams: Stream[] = [];
+  private pending = new Map<LobbyTopic, number>();
+  private timer: ReturnType<typeof setTimeout> | undefined;
+  private service: LobbyService | undefined;
+  private unsubTopics: (() => void) | undefined;
+  private unsubFeed: (() => void) | undefined;
+  private unsubFeedWatch: (() => void) | undefined;
+  private readonly unsubNotices: () => void;
+  private lastReply = "";
+  private readonly heartbeatMs: number;
+  constructor(heartbeatMs: number = HEARTBEAT_MS) {
+    this.heartbeatMs = heartbeatMs;
+    this.unsubNotices = onNotice((notice) => this.notice(notice));
+  }
+
+  /** Open streams (one per browser tab watching). */
+  clients(): number {
+    return this.streams.length;
+  }
+
+  /** Follow `service`'s topics and feed; open streams hear `hello` again. */
+  attach(service: LobbyService): void {
+    this.detach();
+    this.service = service;
+    this.unsubTopics = lobbyTopics.subscribe((topic, version) => this.changed(topic, version));
+    const feed = service.feed;
+    this.lastReply = feed.reply;
+    this.unsubFeed = feed.onChange(() => this.scheduleFlush());
+    this.unsubFeedWatch = watchFeed(feed);
+  }
+
+  /** Stop following the service (streams stay open across a rebind). */
+  detach(): void {
+    this.unsubTopics?.();
+    this.unsubFeed?.();
+    this.unsubFeedWatch?.();
+    this.unsubTopics = undefined;
+    this.unsubFeed = undefined;
+    this.unsubFeedWatch = undefined;
+    this.service = undefined;
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = undefined;
+    this.pending.clear();
+  }
+
+  /** Open a stream; closes the oldest past the cap, says `hello`. */
+  add(_req: IncomingMessage, res: ServerResponse, query: { activityAfter?: number; thoughtsAfter?: number; chatAfter?: number }): void {
+    if (this.streams.length >= MAX_STREAMS) this.dropOldest();
+    res.writeHead(200, { "Content-Type": "text/event-stream; charset=utf-8", "Cache-Control": "no-store", Connection: "keep-alive" });
+    const stream: Stream = {
+      res,
+      beat: setInterval(() => this.ping(stream), this.heartbeatMs),
+      activityAfter: query.activityAfter ?? 0,
+      thoughtsAfter: query.thoughtsAfter ?? 0,
+      chatAfter: query.chatAfter ?? 0,
+    };
+    if (typeof stream.beat === "object" && "unref" in stream.beat) (stream.beat as unknown as { unref(): void }).unref();
+    this.streams.push(stream);
+    res.write(`retry: 2000\n${frame({ type: "hello", versions: lobbyTopics.versions() })}`);
+    this.flushFeed(stream);
+  }
+
+  /** Forget a stream (its request closed). */
+  remove(res: ServerResponse): void {
+    const index = this.streams.findIndex((stream) => stream.res === res);
+    if (index < 0) return;
+    const [stream] = this.streams.splice(index, 1);
+    clearInterval(stream!.beat);
+  }
+
+  /** Say `hello` again on every open stream (after a rebind). */
+  hello(): void {
+    for (const stream of [...this.streams]) this.send(stream, frame({ type: "hello", versions: lobbyTopics.versions() }));
+  }
+
+  /** A lobby notice: every open stream hears it, and `notices` moves on. */
+  private notice(notice: Notice): void {
+    const text = frame({ type: "notice", text: notice.text, level: notice.level });
+    for (const stream of [...this.streams]) this.send(stream, text);
+    lobbyTopics.bump("notices");
+  }
+
+  /** Close every stream and stop following the service. */
+  close(): void {
+    this.detach();
+    this.unsubNotices();
+    for (const stream of this.streams) {
+      clearInterval(stream.beat);
+      try {
+        stream.res.end();
+      } catch {
+        // Already gone; forgetting it is enough.
+      }
+    }
+    this.streams = [];
+  }
+
+  private dropOldest(): void {
+    const oldest = this.streams.shift();
+    if (!oldest) return;
+    clearInterval(oldest.beat);
+    try {
+      oldest.res.end();
+    } catch {
+      // Already gone; forgetting it is enough.
+    }
+  }
+
+  private send(stream: Stream, text: string): void {
+    try {
+      stream.res.write(text);
+    } catch {
+      this.remove(stream.res);
+    }
+  }
+
+  private ping(stream: Stream): void {
+    this.send(stream, ":ping\n\n");
+  }
+
+  /** A topic changed; at most one message per topic per coalescing window. */
+  changed(topic: LobbyTopic, version: number): void {
+    this.pending.set(topic, version);
+    this.scheduleFlush();
+  }
+
+  private scheduleFlush(): void {
+    if (this.timer) return;
+    this.timer = setTimeout(() => {
+      this.timer = undefined;
+      this.flushPending();
+      this.flushFeedAll();
+    }, COALESCE_MS);
+    if (typeof this.timer === "object" && "unref" in this.timer) (this.timer as unknown as { unref(): void }).unref();
+  }
+
+  private flushPending(): void {
+    const changed = [...this.pending];
+    this.pending.clear();
+    for (const [topic, version] of changed) {
+      const text = frame({ type: "changed", topic, version });
+      for (const stream of [...this.streams]) this.send(stream, text);
+    }
+  }
+
+  private flushFeedAll(): void {
+    for (const stream of [...this.streams]) this.flushFeed(stream);
+  }
+
+  /** New feed entries past the stream's cursors, and the reply text when it moved. */
+  private flushFeed(stream: Stream): void {
+    const feed = this.service?.feed;
+    if (!feed) return;
+    const activity = feed.activity.filter((entry) => entry.id > stream.activityAfter);
+    const thoughts = feed.thoughts.filter((entry) => entry.id > stream.thoughtsAfter);
+    const chat = feed.chat.filter((entry) => entry.id > stream.chatAfter);
+    for (const entry of activity) stream.activityAfter = Math.max(stream.activityAfter, idOf(entry));
+    for (const entry of thoughts) stream.thoughtsAfter = Math.max(stream.thoughtsAfter, idOf(entry));
+    for (const entry of chat) stream.chatAfter = Math.max(stream.chatAfter, idOf(entry));
+    if (activity.length > 0 || thoughts.length > 0 || chat.length > 0) {
+      this.send(stream, frame({ type: "feed", activity, thoughts, chat }));
+    }
+    if (feed.reply !== this.lastReply) {
+      this.lastReply = feed.reply;
+      this.send(stream, frame({ type: "reply", text: feed.reply }));
+    }
+  }
+}

package/src/webui/files.ts

@@ -0,0 +1,88 @@
+/**
+ * Preview images over HTTP: `GET /files/preview/<task>/<name>`. Only files
+ * under that task's preview dir (resolved with `realpath`, so symlinks cannot
+ * escape it), only `.png/.jpg/.jpeg/.gif/.webp`, with the right type and
+ * `nosniff`. The session cookie is required, like everywhere else.
+ */
+import type { ServerResponse } from "node:http";
+import { readFile, realpath } from "node:fs/promises";
+import { extname, join, relative, resolve, sep } from "node:path";
+import { tmpdir } from "node:os";
+import { previewDir } from "../ask/relay.ts";
+import { applyBaseHeaders, HttpError, sendError } from "./api/index.ts";
+
+const PREVIEW_TYPES: Record<string, string> = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+};
+
+function previewsRoot(): string {
+  return join(tmpdir(), "bot-lobby-previews");
+}
+
+/** Whether `task`/`name` name a file without reaching outside their folder. */
+export function isPreviewName(task: string, name: string): boolean {
+  if (!/^[\w.-]+$/.test(task) || !/^[\w.-]+$/.test(name)) return false;
+  const ext = extname(name).toLowerCase();
+  return PREVIEW_TYPES[ext] !== undefined;
+}
+
+/** An absolute image path under the previews root as its preview URL, if it is one. */
+export function previewUrlFor(absPath: string): string | undefined {
+  const root = previewsRoot();
+  const resolved = resolve(absPath);
+  if (resolved !== root && !resolved.startsWith(root + sep)) return undefined;
+  const rel = relative(root, resolved);
+  const [task, name, ...rest] = rel.split(sep);
+  if (!task || !name || rest.length > 0 || !isPreviewName(task, name)) return undefined;
+  return `/files/preview/${task}/${name}`;
+}
+
+/** Every absolute preview path in a prompt payload as its preview URL. */
+export function rewritePreviewImages(payload: unknown): unknown {
+  if (typeof payload === "string") return previewUrlFor(payload) ?? payload;
+  if (Array.isArray(payload)) return payload.map(rewritePreviewImages);
+  if (payload && typeof payload === "object") {
+    return Object.fromEntries(Object.entries(payload as Record<string, unknown>).map(([key, value]) => [key, rewritePreviewImages(value)]));
+  }
+  return payload;
+}
+
+/** The preview file's bytes, jailed to its task's preview dir, or undefined when refused. */
+export async function readPreview(task: string, name: string): Promise<{ body: Buffer; type: string } | undefined> {
+  if (!isPreviewName(task, name)) return undefined;
+  let real: string;
+  try {
+    real = await realpath(join(previewDir(task), name));
+  } catch {
+    return undefined;
+  }
+  let base: string;
+  try {
+    base = await realpath(previewDir(task));
+  } catch {
+    return undefined;
+  }
+  if (real !== base && !real.startsWith(base + sep)) return undefined;
+  try {
+    return { body: await readFile(real), type: PREVIEW_TYPES[extname(name).toLowerCase()]! };
+  } catch {
+    return undefined;
+  }
+}
+
+/** Serve one preview; 401 without the cookie, 404 for anything jailed away. */
+export async function servePreview(res: ServerResponse, task: string, name: string, signedIn: boolean): Promise<void> {
+  if (!signedIn) {
+    sendError(res, "unauthorized", "open the link Pi printed", 401);
+    return;
+  }
+  const found = await readPreview(task, name);
+  if (!found) throw new HttpError(404, "not_found", "no such preview");
+  applyBaseHeaders(res);
+  res.writeHead(200, { "Content-Type": found.type, "Cache-Control": "no-store" });
+  res.end(found.body);
+}

package/src/webui/notices.ts

@@ -0,0 +1,61 @@
+/**
+ * Lobby notices that reach the web page as toasts. Two sources: the `notice`
+ * on an action's API reply, and the feed's LOBBY warnings and errors (info
+ * and success stay activity lines, not toasts). A later web server forwards
+ * each one on the event stream and bumps the `notices` topic. Process-global
+ * like the feed, so a notice raised before the server starts is simply lost.
+ */
+import type { ActivityKind, LobbyFeed } from "../lobby/feed.ts";
+
+export type NoticeLevel = "info" | "success" | "warning" | "error";
+
+export interface Notice {
+  text: string;
+  level: NoticeLevel;
+}
+
+type NoticeListener = (notice: Notice) => void;
+
+const listeners = new Set<NoticeListener>();
+
+/** Tell every listener; blank text is dropped. */
+export function pushNotice(text: string, level: NoticeLevel = "info"): void {
+  const body = text.trim();
+  if (!body) return;
+  for (const listener of [...listeners]) listener({ text: body, level });
+}
+
+/** Hear every notice; returns the unsubscribe function. */
+export function onNotice(listener: NoticeListener): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+/** The `notice` string on an API reply, when it carries one. */
+export function noticeText(result: unknown): string | undefined {
+  if (typeof result !== "object" || result === null) return undefined;
+  const notice = (result as { notice?: unknown }).notice;
+  return typeof notice === "string" && notice.trim() ? notice : undefined;
+}
+
+/**
+ * Forward the feed's LOBBY warnings and errors as notices. Entries already in
+ * the feed when this is called are not replayed, so a rebind does not re-toast
+ * the log; returns the unsubscribe function.
+ */
+export function watchFeed(feed: LobbyFeed): () => void {
+  let after = feed.activity.at(-1)?.id ?? 0;
+  return feed.onChange(() => {
+    for (const entry of feed.activity) {
+      if (entry.id <= after) continue;
+      if (entry.source === "LOBBY" && (entry.kind === "warning" || entry.kind === "error")) pushNotice(entry.text, kindLevel(entry.kind));
+    }
+    after = feed.activity.at(-1)?.id ?? after;
+  });
+}
+
+function kindLevel(kind: ActivityKind): NoticeLevel {
+  return kind;
+}

package/src/webui/open.ts

@@ -0,0 +1,35 @@
+/**
+ * Open a URL in the platform's browser: Termux, macOS, Windows or Linux.
+ * Over an SSH session there is no browser to open, so nothing is attempted.
+ * Detached, errors ignored, never throws: true when a browser was attempted.
+ */
+import { spawn } from "node:child_process";
+
+export interface OpenDeps {
+  spawn?: typeof spawn;
+  env?: NodeJS.ProcessEnv;
+  platform?: NodeJS.Platform;
+}
+
+function launch(run: typeof spawn, command: string, args: string[]): boolean {
+  try {
+    const child = run(command, args, { detached: true, stdio: "ignore" });
+    child.on("error", () => {});
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Open `url` in the desktop browser; false when none was attempted. */
+export function openBrowser(url: string, deps?: OpenDeps): boolean {
+  const run = deps?.spawn ?? spawn;
+  const env = deps?.env ?? process.env;
+  const platform = deps?.platform ?? process.platform;
+  if (env.SSH_CONNECTION || env.SSH_TTY) return false;
+  if (env.TERMUX_VERSION) return launch(run, "termux-open-url", [url]);
+  if (platform === "darwin") return launch(run, "open", [url]);
+  if (platform === "win32") return launch(run, "cmd", ["/c", "start", '""', url]);
+  return launch(run, "xdg-open", [url]);
+}