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

package/src/webui/api/lobby.ts

@@ -0,0 +1,91 @@
+/**
+ * The Lobby tab over HTTP: one snapshot (task header, runs, newest chat,
+ * streaming reply, activity, thoughts, older-chat flag), older chat history,
+ * sending text to the oracle, and stopping its turn. Bounds come from the
+ * feed module, so the page sees exactly what the terminal keeps.
+ */
+import { MAX_ACTIVITY, MAX_CHAT, MAX_THOUGHTS } from "../../lobby/feed.ts";
+import type { Task } from "../../schemas/task.ts";
+import type { ApiContext } from "./index.ts";
+import { fail } from "./index.ts";
+import { taskSteps } from "./plan-facts.ts";
+import type { LobbySnapshot, SnapshotTask } from "../protocol.ts";
+
+/** Plan facts the header shows: step progress plus the step under way, if any. */
+function planFacts(task: Task): Pick<SnapshotTask, "progress" | "currentStep"> {
+  const steps = taskSteps(task);
+  if (steps.length === 0) return {};
+  const current = steps.find((step) => step.status === "current");
+  return {
+    progress: { done: steps.filter((step) => step.status === "done").length, total: steps.length },
+    ...(current ? { currentStep: current.text } : {}),
+  };
+}
+
+function taskOf(ctx: ApiContext): LobbySnapshot["task"] {
+  const task = ctx.service.zen().task;
+  if (!task) return undefined;
+  return {
+    id: task.id,
+    title: task.title,
+    state: task.state,
+    ...(task.track ? { track: { path: task.track.path, size: task.track.size } } : {}),
+    domains: [...(task.domains ?? [])],
+    ...(task.git ? { git: { branch: task.git.branch, ...(task.git.from ? { from: task.git.from } : {}) } } : {}),
+    ...planFacts(task),
+  };
+}
+
+/** What the Lobby tab shows, read in one call. */
+export function lobbySnapshot(ctx: ApiContext): LobbySnapshot {
+  const service = ctx.service;
+  const feed = service.feed;
+  const reply = feed.reply;
+  return {
+    ...(taskOf(ctx) ? { task: taskOf(ctx)! } : {}),
+    runs: [...service.zen().runs],
+    chat: feed.chat.slice(-MAX_CHAT).map((entry) => ({ id: entry.id, at: entry.at, role: entry.role, text: entry.text })),
+    ...(reply ? { reply } : {}),
+    activity: feed.activity.slice(-MAX_ACTIVITY).map((entry) => ({
+      id: entry.id,
+      at: entry.at,
+      source: entry.source,
+      text: entry.text,
+      kind: entry.kind,
+      pending: entry.pending,
+    })),
+    thoughts: feed.thoughts.slice(-MAX_THOUGHTS).map((entry) => ({
+      id: entry.id,
+      at: entry.at,
+      source: entry.source,
+      text: entry.text,
+      live: entry.live,
+    })),
+    hasOlderChat: feed.chatOlder,
+  };
+}
+
+/** Older chat from the session file, before `before` (newest 50, oldest first). */
+export function lobbyHistory(body: { before?: number }, ctx: ApiContext): { entries: unknown[]; hasOlder: boolean } {
+  const all = [...ctx.service.chatHistory()];
+  const older = body.before === undefined ? all : all.filter((entry) => entry.id < body.before!);
+  const entries = older.slice(-50);
+  return { entries, hasOlder: older.length > entries.length };
+}
+
+/** Text for the oracle; a notice when it was not simply sent. */
+export function lobbySend(body: { text: string }, ctx: ApiContext): { notice?: string } {
+  if (!body.text.trim()) return { notice: "type something first" };
+  const notice = ctx.service.toOracle(body.text);
+  return notice ? { notice } : {};
+}
+
+/** Stop the oracle's turn. */
+export function lobbyAbort(ctx: ApiContext): Record<string, never> {
+  try {
+    ctx.service.abortMaster();
+  } catch (error) {
+    fail(500, "failed", (error as Error).message);
+  }
+  return {};
+}

package/src/webui/api/metrics.ts

@@ -0,0 +1,63 @@
+/**
+ * The Metrics tab over HTTP: the KPI tiles, the per-model groups, where the
+ * time goes, and what the classifier did — the same figures the terminal
+ * tab draws, as data. Search narrows runs exactly like the tab's `/`.
+ */
+import { aggregateMetrics, collectMetrics, sortGroups, summarizeClassifier, taskStats, taskTimesByModel, type GroupBy, type MetricRecord } from "../../state/metrics.ts";
+import { filterRecords } from "../../lobby/models/metrics.ts";
+import type { MetricsData } from "../protocol.ts";
+import type { ApiContext } from "./index.ts";
+
+function timed(records: readonly MetricRecord[]): MetricRecord[] {
+  return records.filter((record) => record.status !== "cancelled" && record.durationMs > 0);
+}
+
+/** The KPI row as data: runs, success, average run, cost, tasks. */
+function tilesOf(records: readonly MetricRecord[], stats: ReturnType<typeof taskStats>): MetricsData["tiles"] {
+  const done = timed(records);
+  const ok = records.filter((record) => record.status === "success").length;
+  const cost = records.reduce((sum, record) => sum + (record.cost ?? 0), 0);
+  const avg = done.length > 0 ? done.reduce((sum, record) => sum + record.durationMs, 0) / done.length : 0;
+  const sorted = done.map((record) => record.durationMs).sort((a, b) => a - b);
+  const p90 = sorted.length > 0 ? sorted[Math.min(sorted.length - 1, Math.ceil(0.9 * sorted.length) - 1)]! : 0;
+  return {
+    runs: records.length,
+    successes: ok,
+    stalls: records.filter((record) => record.stalled || record.status === "timeout").length,
+    avgMs: avg,
+    p90Ms: p90,
+    cost,
+    completed: stats.completed,
+    active: stats.active,
+    avgCompleteMs: stats.avgCompleteMs,
+  };
+}
+
+/** Each agent's share of all run time, longest first. */
+function shareOf(records: readonly MetricRecord[]): MetricsData["timeShare"]["byAgent"] {
+  const byAgent = new Map<string, { runs: number; ms: number }>();
+  for (const record of timed(records)) {
+    const entry = byAgent.get(record.agent) ?? { runs: 0, ms: 0 };
+    entry.runs += 1;
+    entry.ms += record.durationMs;
+    byAgent.set(record.agent, entry);
+  }
+  const total = [...byAgent.values()].reduce((sum, entry) => sum + entry.ms, 0);
+  return [...byAgent.entries()]
+    .sort((a, b) => b[1].ms - a[1].ms)
+    .map(([agent, entry]) => ({ agent, runs: entry.runs, ms: entry.ms, share: total > 0 ? entry.ms / total : 0 }));
+}
+
+/** The dashboard figures for one grouping and search. */
+export function metricsGet(body: { groupBy: GroupBy; query?: string }, ctx: ApiContext): MetricsData {
+  const tasks = ctx.service.tasks();
+  const records = filterRecords(collectMetrics(ctx.service.metrics(), tasks), body.query);
+  const stats = taskStats(tasks);
+  const classifier = summarizeClassifier(ctx.service.classifierMetrics?.() ?? [], records);
+  return {
+    tiles: tilesOf(records, stats),
+    groups: sortGroups(aggregateMetrics(records, body.groupBy), "runs"),
+    timeShare: { byAgent: shareOf(records), taskTimes: taskTimesByModel(tasks, records) },
+    ...(classifier ? { classifier } : {}),
+  };
+}

package/src/webui/api/plan-facts.ts

@@ -0,0 +1,29 @@
+/**
+ * What the Lobby header and the Tasks calls both read of a task's plan: the
+ * worker records as runs, and the plan's checklist. Kept here (not via
+ * `persistedRuns`) so the server never loads the TUI.
+ */
+import { planChecklist, type PlanStep } from "../../pi/plan-checklist.ts";
+import type { AgentRun } from "../../schemas/findings.ts";
+import type { Task } from "../../schemas/task.ts";
+
+/** Worker records as runs, the same projection the terminal checklist reads. */
+export function persistedTaskRuns(task: Task): AgentRun[] {
+  return (task.workerRuns ?? []).map((record) => ({
+    runId: record.runId,
+    taskId: task.id,
+    domain: record.domain,
+    role: "worker" as const,
+    status: record.status,
+    instruction: record.instruction,
+    output: "",
+    attempts: 1,
+    startedAt: record.startedAt,
+    ...(record.finishedAt ? { finishedAt: record.finishedAt } : {}),
+  }));
+}
+
+/** The plan's steps with their state; none when the task has no plan. */
+export function taskSteps(task: Task): PlanStep[] {
+  return task.plan ? planChecklist(task.plan, persistedTaskRuns(task)) : [];
+}

package/src/webui/api/planner.ts

@@ -0,0 +1,98 @@
+/**
+ * The Plan tab over HTTP: reading the planning session, starting a new one,
+ * sending a message, seating members, retrying, commenting on a draft line,
+ * answering the round's questions and saving the draft. Actions answer with
+ * the same notice text the terminal shows.
+ */
+import { MEMBER_LABELS } from "../../lobby/planner.ts";
+import type { PanelMember } from "../../schemas/configuration.ts";
+import type { PlannerSnapshot } from "../protocol.ts";
+import type { ApiContext } from "./index.ts";
+import { fail } from "./index.ts";
+
+/** The planning session as the page reads it; absent means no session yet. */
+export function plannerGet(ctx: ApiContext): PlannerSnapshot {
+  const session = ctx.service.planner();
+  if (!session) {
+    return {
+      seats: [...ctx.service.defaultPanel()],
+      members: [],
+      messages: [],
+      questions: [],
+      notes: [],
+      round: 0,
+      limit: ctx.service.planningRounds?.() ?? 0,
+      retryable: false,
+      busy: false,
+    };
+  }
+  return {
+    seats: [...session.seats],
+    members: session.members.map((member) => ({ ...member })),
+    messages: session.messages.map((message) => ({ ...message })),
+    ...(session.reply?.plan ? { draft: session.reply.plan } : {}),
+    questions: session.questions.map((question) => ({ ...question })),
+    notes: session.notes.map((note) => ({ ...note })),
+    round: session.turns,
+    limit: ctx.service.planningRounds?.() ?? 0,
+    retryable: session.retryable,
+    busy: session.busy,
+  };
+}
+
+/** Start over with a fresh planning session, from an issue or nothing. */
+export function plannerNew(body: { seed?: { issue: { number: number; title: string; url?: string }; body: string }; seats?: PanelMember[] }, ctx: ApiContext): { notice: string } {
+  ctx.service.newPlanner(body.seed, body.seats);
+  return { notice: "new planning session — describe the task to plan" };
+}
+
+/** Send a message to the panel; the round runs in the background. */
+export function plannerSend(body: { text: string }, ctx: ApiContext): { notice: string } {
+  if (!body.text.trim()) fail(400, "bad_request", "describe the task to plan");
+  const session = ctx.service.planner() ?? ctx.service.newPlanner(undefined, [...ctx.service.defaultPanel()]);
+  if (session!.busy) fail(409, "conflict", "the panel is still thinking — x stops it");
+  session!.send(body.text).catch(() => {});
+  return { notice: "sent — the panel is on the next round" };
+}
+
+/** Seat or unseat a member for the next round. */
+export function plannerToggleSeat(body: { member: PanelMember }, ctx: ApiContext): { notice: string; seated: boolean } {
+  const session = ctx.service.planner() ?? ctx.service.newPlanner(undefined, [...ctx.service.defaultPanel()]);
+  const seated = session!.toggle(body.member);
+  return { notice: `${MEMBER_LABELS[body.member]} ${seated ? "joins the panel from the next round and sits every round" : "leaves the panel from the next round"}`, seated };
+}
+
+/** Run the last round again; a quiet round has nothing to redo. */
+export function plannerRetry(ctx: ApiContext): { notice: string } {
+  const session = ctx.service.planner();
+  if (!session) fail(404, "not_found", "no planning session");
+  if (!session!.retryable) return { notice: "nothing to retry" };
+  void session!.retry();
+  return { notice: "retrying the round…" };
+}
+
+/** Comment on one line of the draft; it rides with the answers or starts a round. */
+export function plannerCommentLine(body: { line: string; text: string }, ctx: ApiContext): { notice: string } {
+  if (!body.line.trim() || !body.text.trim()) fail(400, "bad_request", "a draft line and a comment are required");
+  const session = ctx.service.planner();
+  if (!session?.reply?.plan) fail(409, "conflict", "there is no draft to comment on yet");
+  const sent = session!.commentOnLine(body.line, body.text);
+  if (sent) return { notice: "comment sent — the panel revises the draft" };
+  if (session!.busy) return { notice: "comment kept — it goes to the panel after this round" };
+  return { notice: "comment kept — it goes with your answers (a answers the questions)" };
+}
+
+/** The oracle puts the round's questions to the user through the questionnaire. */
+export async function plannerAnswer(ctx: ApiContext): Promise<{ notice: string }> {
+  const session = ctx.service.planner();
+  if (!session) fail(404, "not_found", "no planning session");
+  if (!session!.awaitingAnswers) return { notice: session!.busy ? "the panel is still thinking" : "no open questions" };
+  return { notice: await ctx.service.answerPanel() };
+}
+
+/** Save the draft as a pending task; a long plan is first offered a split. */
+export async function plannerSave(ctx: ApiContext): Promise<{ notice: string }> {
+  const session = ctx.service.planner();
+  if (!session?.reply?.plan) fail(409, "conflict", "no plan to save yet — describe a task in the Plan tab");
+  return { notice: await ctx.service.savePlan() };
+}

package/src/webui/api/plans.ts

@@ -0,0 +1,44 @@
+/**
+ * Saved plans over HTTP: reading one, starting it here or in a new background
+ * session, and discarding it. Actions answer with the same notice text the terminal
+ * shows (the terminal asks twice before discarding; the web call is already
+ * an explicit confirmation).
+ */
+import type { PlanDetail } from "../protocol.ts";
+import type { ApiContext } from "./index.ts";
+import { fail } from "./index.ts";
+
+/** Start a saved plan: in this window (`here`) or in a new session of its own. */
+export function plansStart(body: { planId: string; where: "here" | "session"; auto?: boolean }, ctx: ApiContext): { notice: string; key?: string } {
+  const plan = ctx.service.plans().find((entry) => entry.id === body.planId);
+  if (!plan) fail(404, "not_found", `no plan ${body.planId}`);
+  if (body.where === "here") return { notice: ctx.service.startPlanned(plan!) };
+  const session = ctx.service.startSession({ plan: plan!, ...(body.auto ? { auto: true } : {}) });
+  if (typeof session === "string") return { notice: session };
+  return { notice: `started ${session.name} in a new session`, key: session.key };
+}
+
+/** Discard a saved plan; unknown ids are 404. */
+export function plansDiscard(body: { planId: string }, ctx: ApiContext): { notice: string } {
+  const plan = ctx.service.plans().find((entry) => entry.id === body.planId);
+  if (!plan) fail(404, "not_found", `no plan ${body.planId}`);
+  ctx.service.discardPlan(body.planId);
+  return { notice: `discarded ${body.planId}` };
+}
+
+/** One saved plan: its agreed text, the issue it came from and the parts it was split into. */
+export function plansGet(body: { planId: string }, ctx: ApiContext): PlanDetail {
+  const found = ctx.service.plans().find((entry) => entry.id === body.planId);
+  if (!found) fail(404, "not_found", `no plan ${body.planId}`);
+  const plan = found!;
+  return {
+    id: plan.id,
+    title: plan.title,
+    status: plan.status,
+    createdAt: plan.createdAt,
+    brief: plan.brief,
+    ...(plan.issue ? { issue: { number: plan.issue.number, title: plan.issue.title, ...(plan.issue.url ? { url: plan.issue.url } : {}) } } : {}),
+    ...(plan.split ? { split: { part: plan.split.part, of: plan.split.of, titles: [...plan.split.titles], after: [...plan.split.after] } } : {}),
+    ...(plan.startedTaskId ? { startedTaskId: plan.startedTaskId } : {}),
+  };
+}

package/src/webui/api/prompts.ts

@@ -0,0 +1,35 @@
+/**
+ * The question queue over HTTP: listing what waits, answering (the first
+ * answer wins, anywhere), and dismissing. A late answer — the id is gone
+ * because the terminal, another tab or a cancel settled it first — reads as
+ * 409 `question_withdrawn`. Image paths in payloads become preview URLs the
+ * page may load through `GET /files/preview/…`.
+ */
+import { promptHub } from "../../lobby/prompt-hub.ts";
+import type { ApiContext } from "./index.ts";
+import { fail } from "./index.ts";
+import { rewritePreviewImages } from "../files.ts";
+import type { WebPrompt } from "../protocol.ts";
+
+function withPreviewUrls(prompt: WebPrompt): WebPrompt {
+  return { ...prompt, payload: rewritePreviewImages(prompt.payload) };
+}
+
+/** The questions still waiting for an answer, oldest first. */
+export function promptsList(_ctx: ApiContext): { prompts: WebPrompt[] } {
+  return { prompts: promptHub.pending().map(withPreviewUrls) };
+}
+
+/** Answer a question; 409 when it is already settled or unknown. */
+export function promptsAnswer(body: { id: string; answer: unknown }, _ctx: ApiContext): { notice?: string } {
+  if (!promptHub.answer(body.id, body.answer)) {
+    fail(409, "question_withdrawn", "this question is already answered or gone");
+  }
+  return { notice: "answer sent" };
+}
+
+/** Take a question back without an answer (idempotent, so races stay quiet). */
+export function promptsDismiss(body: { id: string }, _ctx: ApiContext): Record<string, never> {
+  promptHub.dismiss(body.id);
+  return {};
+}

package/src/webui/api/quickfix.ts

@@ -0,0 +1,48 @@
+/**
+ * The Quick fix tab over HTTP: the job list newest first, submitting a new
+ * job, cancelling one, running a held one anyway, and moving a held one to a
+ * task in a new session. Actions answer with the same notice text the
+ * terminal shows.
+ */
+import type { ApiContext } from "./index.ts";
+import { fail } from "./index.ts";
+import type { QuickFixJob } from "../../lobby/quickfix.ts";
+
+/** Every job, newest first like the terminal shows them. */
+export function quickfixList(ctx: ApiContext): { jobs: QuickFixJob[] } {
+  return { jobs: [...ctx.service.quickfix.jobs].reverse() };
+}
+
+/** Queue a quick fix; it starts at once when nothing else is running. */
+export function quickfixSubmit(body: { text: string }, ctx: ApiContext): { notice: string; id: string } {
+  if (!body.text.trim()) fail(400, "bad_request", "describe a quick change first");
+  const job = ctx.service.quickfix.submit(body.text);
+  return { notice: ctx.service.quickfix.running?.id === job.id ? `${job.id} started` : `${job.id} queued behind the running quick fix`, id: job.id };
+}
+
+/** Cancel a queued or running job; finished jobs are left alone. */
+export function quickfixCancel(body: { id: string }, ctx: ApiContext): { notice: string } {
+  const job = ctx.service.quickfix.jobs.find((entry) => entry.id === body.id);
+  if (!job) fail(404, "not_found", `no quick fix ${body.id}`);
+  if (!ctx.service.quickfix.cancel(body.id)) fail(409, "conflict", `${body.id} already ${job!.status}`);
+  return { notice: `cancelling ${body.id}` };
+}
+
+/** Run a held job anyway: it goes back in the queue and is not sized again. */
+export function quickfixRunAnyway(body: { id: string }, ctx: ApiContext): { notice: string } {
+  const job = ctx.service.quickfix.jobs.find((entry) => entry.id === body.id);
+  if (!job) fail(404, "not_found", `no quick fix ${body.id}`);
+  if (!ctx.service.quickfix.runAnyway(body.id)) fail(409, "conflict", `only a held job runs anyway — ${body.id} is ${job!.status}`);
+  return { notice: `running ${body.id} anyway` };
+}
+
+/** A held job that became a task: it starts in a new session and leaves the queue. */
+export function quickfixMovedToTask(body: { id: string }, ctx: ApiContext): { notice: string; key?: string } {
+  const job = ctx.service.quickfix.jobs.find((entry) => entry.id === body.id);
+  if (!job) fail(404, "not_found", `no quick fix ${body.id}`);
+  if (job!.status !== "held") fail(409, "conflict", `only a held job moves to a task — ${body.id} is ${job!.status}`);
+  const session = ctx.service.startSession({ request: job!.prompt });
+  ctx.service.quickfix.movedToTask(body.id);
+  if (typeof session === "string") return { notice: session };
+  return { notice: `started ${session.name} in a new session`, key: session.key };
+}

package/src/webui/api/sessions.ts

@@ -0,0 +1,114 @@
+/**
+ * Background sessions over HTTP: listing what this window started (with
+ * status and waiting dialogs) plus live sessions in other terminals, reading
+ * a session's conversation, starting, stopping, messaging, switching to, and
+ * answering a session's question. Session keys are the TUI's (`S1`, `S2`, …);
+ * a session running in another terminal stays there and can only be messaged.
+ */
+import type { BackgroundSession, DialogAnswer } from "../../lobby/sessions.ts";
+import type { ApiContext } from "./index.ts";
+import { fail } from "./index.ts";
+import type { BackgroundSessionInfo } from "../protocol.ts";
+
+function infoOf(session: BackgroundSession): BackgroundSessionInfo {
+  return {
+    key: session.key,
+    name: session.name,
+    status: session.status,
+    busy: session.busy,
+    alive: session.alive,
+    ...(session.sessionId ? { sessionId: session.sessionId } : {}),
+    ...(session.planId ? { planId: session.planId } : {}),
+    waiting: session.dialogs.length,
+    dialogs: session.dialogs.map((dialog) => ({ ...dialog })),
+  };
+}
+
+/** Background sessions this window started, plus live sessions elsewhere. */
+export function sessionsList(ctx: ApiContext): { background: BackgroundSessionInfo[]; live: unknown[] } {
+  return { background: ctx.service.sessions().map(infoOf), live: [...ctx.service.liveSessions()] };
+}
+
+/** Find a background session by its key or its pi session id. */
+function backgroundOf(ctx: ApiContext, key?: string, sessionId?: string): BackgroundSession | undefined {
+  if (!key && !sessionId) return undefined;
+  return ctx.service.sessions().find((session) => (key && session.key === key) || (sessionId && session.sessionId === sessionId));
+}
+
+/** One session's conversation, newest 50 before `before`, oldest first. */
+export function sessionsChat(body: { key?: string; sessionId?: string; before?: number }, ctx: ApiContext): { entries: unknown[]; hasOlder: boolean } {
+  const background = backgroundOf(ctx, body.key, body.sessionId);
+  if (background) return pageChat([...background.feed.chat], background.feed.chatOlder && Boolean(background.sessionId), body.before);
+  if (!body.sessionId) fail(404, "not_found", "no session with that key");
+  return pageChat([...ctx.service.sessionChat(body.sessionId!)], ctx.service.hasOlderChat(body.sessionId!), body.before);
+}
+
+function pageChat(all: unknown[], older: boolean, before?: number): { entries: unknown[]; hasOlder: boolean } {
+  const rest = before === undefined ? all : all.filter((entry) => (entry as { id: number }).id < before);
+  const entries = rest.slice(-50);
+  return { entries, hasOlder: rest.length > entries.length || (before === undefined && older) };
+}
+
+/** Start a task in a new background session, from a request or a saved plan. */
+export function sessionsStart(body: { request?: string; planId?: string; auto?: boolean }, ctx: ApiContext): { notice: string; key?: string } {
+  if (body.request?.trim() && body.planId) fail(400, "bad_request", "start from a request or a plan, not both");
+  if (body.planId) {
+    const plan = ctx.service.plans().find((entry) => entry.id === body.planId);
+    if (!plan) fail(404, "not_found", `no plan ${body.planId}`);
+    const session = ctx.service.startSession({ plan: plan!, ...(body.auto ? { auto: true } : {}) });
+    if (typeof session === "string") return { notice: session };
+    return { notice: `started ${session.name} in a new session`, key: session.key };
+  }
+  if (!body.request?.trim()) fail(400, "bad_request", "describe the task first");
+  const session = ctx.service.startSession({ request: body.request!.trim(), ...(body.auto ? { auto: true } : {}) });
+  if (typeof session === "string") return { notice: session };
+  return { notice: `started ${session.name} in a new session`, key: session.key };
+}
+
+/** Stop a background session this window started; its task keeps its state. */
+export function sessionsStop(body: { key: string }, ctx: ApiContext): { notice: string } {
+  const session = backgroundOf(ctx, body.key);
+  if (!session) fail(404, "not_found", `no session ${body.key}`);
+  session!.stop();
+  return { notice: `stopping ${session!.name}` };
+}
+
+/** Message a session: background ones directly, other terminals through their inbox. */
+export function sessionsMessage(body: { key?: string; sessionId?: string; text: string }, ctx: ApiContext): { notice?: string } {
+  if (!body.key && !body.sessionId) fail(400, "bad_request", "a session key or id is required");
+  if (!body.text.trim()) return { notice: "type something first" };
+  const background = backgroundOf(ctx, body.key, body.sessionId);
+  if (background) {
+    if (!background.alive) fail(409, "conflict", `${background.name} has ended`);
+    background.send(body.text);
+    return {};
+  }
+  return { notice: ctx.service.sendToSession(body.sessionId!, body.text) };
+}
+
+/** Run a session in this window (stopping its background process first). */
+export async function sessionsSwitch(body: { key?: string; sessionId?: string; claimTaskId?: string }, ctx: ApiContext): Promise<{ notice: string }> {
+  if (!body.key && !body.sessionId && !body.claimTaskId) fail(400, "bad_request", "a session key, id or task is required");
+  if (ctx.service.masterBusy()) return { notice: "this window's oracle is working — stop it, then switch" };
+  if (body.claimTaskId) {
+    const task = ctx.service.tasks().find((entry) => entry.id === body.claimTaskId);
+    if (!task) fail(404, "not_found", `no task ${body.claimTaskId}`);
+    return { notice: await ctx.service.switchTo({ name: task!.title, claimTaskId: body.claimTaskId }) };
+  }
+  const background = backgroundOf(ctx, body.key, body.sessionId);
+  if (background) {
+    return { notice: await ctx.service.switchTo({ name: background.name, ...(background.sessionId ? { sessionId: background.sessionId } : {}), background }) };
+  }
+  const live = ctx.service.liveSessions().find((session) => session.sessionId === body.sessionId);
+  const name = live?.name ?? "that session";
+  return { notice: `${name} is running in another terminal — switch there, or close it first and resume it here` };
+}
+
+/** Answer a question a background session waits on. */
+export function sessionsAnswer(body: { key: string; dialogId: string; answer: DialogAnswer }, ctx: ApiContext): { notice: string } {
+  const session = backgroundOf(ctx, body.key);
+  if (!session) fail(404, "not_found", `no session ${body.key}`);
+  if (!session!.dialogs.some((dialog) => dialog.id === body.dialogId)) fail(404, "not_found", `no question ${body.dialogId} on ${body.key}`);
+  session!.answer(body.dialogId, body.answer);
+  return { notice: "answer sent" };
+}

package/src/webui/api/settings.ts

@@ -0,0 +1,93 @@
+/**
+ * `settings.get` / `settings.set`: the effective bot-lobby config (never a
+ * secret) and the models Pi offers. A set merges the patch over the current
+ * config, normalises it through the same `resolveConfig` the terminal uses and
+ * saves it the way the settings menu does, so the terminal sees the change.
+ * The one terminal wording reused here is the port's; everything else the
+ * normaliser clamps or drops, so no unknown field is ever written.
+ */
+import { resolveConfig, type BotLobbyConfig } from "../../schemas/configuration.ts";
+import { loadConfig, saveConfig } from "../../state/project.ts";
+import { lobbyTopics } from "../../lobby/topics.ts";
+import type { SettingsInfo } from "../protocol.ts";
+import type { ApiContext } from "./index.ts";
+import { fail } from "./index.ts";
+
+const SECRET_KEY = /^(api[-_]?key|auth[-_]?key|access[-_]?token|refresh[-_]?token|token|secret|password|authorization)$/i;
+
+/** A deep copy of `value` with secret-looking fields removed at every depth. */
+export function stripSecrets<T>(value: T): T {
+  if (Array.isArray(value)) return value.map((entry) => stripSecrets(entry)) as unknown as T;
+  if (typeof value !== "object" || value === null) return value;
+  const out: Record<string, unknown> = {};
+  for (const [key, entry] of Object.entries(value as Record<string, unknown>)) {
+    if (!SECRET_KEY.test(key)) out[key] = stripSecrets(entry);
+  }
+  return out as T;
+}
+
+/** Merge `patch` over `base`; nested plain objects merge, everything else replaces. */
+export function mergeConfig(base: unknown, patch: unknown): unknown {
+  if (!isPlain(base) || !isPlain(patch)) return patch;
+  const out: Record<string, unknown> = { ...base };
+  for (const [key, value] of Object.entries(patch)) {
+    out[key] = isPlain(value) && isPlain(out[key]) ? mergeConfig(out[key], value) : value;
+  }
+  return out;
+}
+
+function isPlain(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function readConfig(ctx: ApiContext): BotLobbyConfig {
+  return ctx.service.config?.() ?? loadConfig();
+}
+
+function writeConfig(ctx: ApiContext, config: BotLobbyConfig): void {
+  if (ctx.service.saveConfig) ctx.service.saveConfig(config);
+  else saveConfig(config);
+}
+
+/** Reject a port that is not 0 or 1-65535, with the terminal's wording. */
+function checkPort(patch: Record<string, unknown>): void {
+  const lobby = isPlain(patch.lobby) ? patch.lobby : undefined;
+  const web = lobby && isPlain(lobby.web) ? lobby.web : undefined;
+  const port = web?.port;
+  if (port === undefined) return;
+  if (typeof port !== "number" || !Number.isInteger(port) || port < 0 || port > 65535) {
+    fail(400, "bad_request", `"${String(port)}" is not a port (0, or 1-65535).`);
+  }
+}
+
+function agentEntries(patch: Record<string, unknown>): unknown[] {
+  const agents = isPlain(patch.agents) ? Object.values(patch.agents) : [];
+  return [patch.master, ...agents, patch.researcher, patch.quickFix, patch.planner, patch.scout];
+}
+
+/** Reject a time limit that is not a positive number, with the terminal's wording. */
+function checkTimeouts(patch: Record<string, unknown>): void {
+  for (const entry of agentEntries(patch)) {
+    const timeout = isPlain(entry) ? entry.timeoutMs : undefined;
+    if (timeout === undefined) continue;
+    if (typeof timeout !== "number" || !Number.isFinite(timeout) || timeout <= 0) {
+      fail(400, "bad_request", `"${String(timeout)}" is not a positive number of minutes.`);
+    }
+  }
+}
+
+/** The page's first settings call. */
+export function settingsGet(ctx: ApiContext): SettingsInfo {
+  return { config: stripSecrets(readConfig(ctx)), models: ctx.service.models?.() ?? [] };
+}
+
+/** Merge, normalise and save the patch; the terminal rerenders and rereads the config. */
+export function settingsSet(body: { patch: Record<string, unknown> }, ctx: ApiContext): { config: BotLobbyConfig } {
+  checkPort(body.patch);
+  checkTimeouts(body.patch);
+  const config = stripSecrets(resolveConfig(mergeConfig(readConfig(ctx), body.patch)));
+  writeConfig(ctx, config);
+  ctx.service.configChanged?.();
+  lobbyTopics.bump("status");
+  return { config };
+}