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

package/src/webui/api/git.ts

@@ -0,0 +1,98 @@
+/**
+ * The Git tab over HTTP: the open pull requests with their checks, size and
+ * review marks; one pull request with its files and discussion, our review
+ * and Jev's read; starting and stopping a review; asking Jev. Everything goes
+ * through the lobby's `PullsState` and `PullReviews`, so the terminal and the
+ * page see one set of reviews. Nothing is ever posted to GitHub.
+ *
+ * Only types come from `src/lobby/pulls.ts` and `pr-review.ts` (erased at
+ * compile time): the review module loads the agent runner, and the server
+ * needs none of it.
+ */
+import type { PullDetail, PullSummary } from "../../lobby/pulls.ts";
+import type { PullReadState, PullReview } from "../../lobby/pr-review.ts";
+import type { GitPull, GitPulls, PullInfo, PullReadInfo, PullReviewInfo, PullReviewMark } from "../protocol.ts";
+import type { ApiContext } from "./index.ts";
+import { ghRefusal } from "./gh-error.ts";
+
+/** The pull request has commits the review did not see (mirrors `isStale`). */
+function staleOf(review: PullReview, headSha: string | undefined): boolean {
+  return Boolean(review.headSha && headSha && review.headSha !== headSha);
+}
+
+function markOf(review: PullReview | undefined, headSha: string | undefined): PullReviewMark | undefined {
+  if (!review) return undefined;
+  return { status: review.status, ...(review.verdict ? { verdict: review.verdict } : {}), stale: staleOf(review, headSha) };
+}
+
+function pullInfo(pull: PullSummary, review: PullReview | undefined): PullInfo {
+  const { headSha, ...rest } = pull;
+  const mark = markOf(review, headSha);
+  return { ...rest, labels: [...rest.labels], ...(mark ? { review: mark } : {}) };
+}
+
+function reviewInfo(review: PullReview, headSha: string | undefined): PullReviewInfo {
+  const { headSha: _seen, ...rest } = review;
+  return { ...rest, steps: [...rest.steps], stale: staleOf(review, headSha) };
+}
+
+function readInfo(state: PullReadState): PullReadInfo {
+  return { ...state, ...(state.read ? { read: { ...state.read } } : {}) };
+}
+
+/** The open pull requests; read from `gh` the first time or when `refresh` asks (a failure is not retried until asked). */
+export async function gitPulls(body: { refresh?: boolean }, ctx: ApiContext): Promise<GitPulls> {
+  const state = ctx.service.pulls;
+  if (body.refresh || (!state.loaded && !state.error)) {
+    state.forget();
+    await state.refresh();
+  }
+  const pulls = state.pulls.map((pull) => pullInfo(pull, ctx.service.reviews.review(pull.number)));
+  return { pulls, loading: state.loading, loaded: state.loaded, ...(state.error ? { error: state.error } : {}) };
+}
+
+/** One pull request with its files, description, reviews and comments, our review and Jev's read. */
+export async function gitPull(body: { number: number }, ctx: ApiContext): Promise<GitPull> {
+  const detail: PullDetail | undefined = await ctx.service.pulls.detail(body.number);
+  if (!detail) ghRefusal(ctx.service.pulls.error, `#${body.number}`);
+  const { body: text, state, mergeable, files, notes, ...summary } = detail!;
+  const review = ctx.service.reviews.review(body.number);
+  const read = ctx.service.reviews.reads.get(body.number);
+  return {
+    pull: {
+      ...pullInfo(summary, review),
+      body: text,
+      ...(state ? { state } : {}),
+      ...(mergeable ? { mergeable } : {}),
+      files: files.map((file) => ({ ...file })),
+      notes: notes.map((note) => ({ ...note })),
+    },
+    ...(review ? { review: reviewInfo(review, detail!.headSha) } : {}),
+    ...(read ? { read: readInfo(read) } : {}),
+  };
+}
+
+/** Start a review by a read-only agent; it runs on, streaming into the activity log. */
+export function gitReview(body: { number: number; focus?: string }, ctx: ApiContext): { notice: string } {
+  const { reviews, pulls } = ctx.service;
+  const number = body.number;
+  if (reviews.running(number)) return { notice: `already reviewing #${number}` };
+  const focus = body.focus?.trim();
+  const detail = pulls.details.get(number);
+  reviews.start(number, { ...(focus ? { focus } : {}), ...(detail ? { detail } : {}) }).catch(() => undefined);
+  return { notice: `reviewing #${number}${focus ? ` — looking at: ${focus.length > 40 ? `${focus.slice(0, 39)}…` : focus}` : ""} — it streams into the activity log` };
+}
+
+/** Stop a running review. */
+export function gitCancelReview(body: { number: number }, ctx: ApiContext): { notice: string } {
+  const stopped = ctx.service.reviews.cancel(body.number);
+  return { notice: stopped ? `stopping the review of #${body.number}` : `no review of #${body.number} is running` };
+}
+
+/** Ask Jev for a quick read; the answer arrives with `git.pull`. */
+export function gitJev(body: { number: number }, ctx: ApiContext): { notice: string } {
+  const { reviews, pulls } = ctx.service;
+  if (reviews.reads.get(body.number)?.status === "running") return { notice: `Jev is already reading #${body.number}` };
+  reviews.readWithJev(body.number, pulls.details.get(body.number)).catch(() => undefined);
+  return { notice: `asking Jev to read #${body.number}…` };
+}

package/src/webui/api/index.ts

@@ -0,0 +1,379 @@
+/**
+ * The router: `POST /api/<group>.<action>` with a JSON object body, answered
+ * `{ok:true,result}` or `{ok:false,error,code}`. One TypeBox schema per
+ * request; groups and actions live in a null-prototype map so inherited
+ * names (`__proto__`, `constructor`) are never callable. Shared response
+ * helpers live here too, so static/stream failures answer the same shape.
+ */
+import type { ServerResponse } from "node:http";
+import { Type, type TObject } from "typebox";
+import { Compile } from "typebox/compile";
+import { statusFor, type ApiName, type ErrorCode } from "../protocol.ts";
+import type { LobbyService } from "../../lobby/service.ts";
+import { statusGet } from "./status.ts";
+import { lobbyAbort, lobbyHistory, lobbySend, lobbySnapshot } from "./lobby.ts";
+import { promptsAnswer, promptsDismiss, promptsList } from "./prompts.ts";
+import { plannerAnswer, plannerCommentLine, plannerGet, plannerNew, plannerRetry, plannerSend, plannerToggleSeat, plannerSave } from "./planner.ts";
+import { quickfixCancel, quickfixList, quickfixMovedToTask, quickfixRunAnyway, quickfixSubmit } from "./quickfix.ts";
+import { tasksArchive, tasksArchived, tasksAuto, tasksComment, tasksComments, tasksDelete, tasksGet, tasksList, tasksMessage, tasksRestore } from "./tasks.ts";
+import { metricsGet } from "./metrics.ts";
+import { knowledgeAdd, knowledgeComment, knowledgeEdit, knowledgeFiles, knowledgeOpen, knowledgeRemove, knowledgeReplaceFile, knowledgeUnnote } from "./knowledge.ts";
+import { excalidrawAdd, excalidrawCheck, excalidrawCreate, excalidrawList, excalidrawRemove, excalidrawRename, excalidrawReveal, excalidrawToggleAgent, excalidrawToggleAll, excalidrawToggleContribute } from "./excalidraw.ts";
+import { plansDiscard, plansGet, plansStart } from "./plans.ts";
+import { gitCancelReview, gitJev, gitPull, gitPulls, gitReview } from "./git.ts";
+import { issuesCreate, issuesGet, issuesList } from "./issues.ts";
+import { sessionsAnswer, sessionsChat, sessionsList, sessionsMessage, sessionsStart, sessionsStop, sessionsSwitch } from "./sessions.ts";
+import { settingsGet, settingsSet } from "./settings.ts";
+import { noticeText, pushNotice } from "../notices.ts";
+
+/** What a handler reads besides the request body. */
+export interface ApiContext {
+  service: LobbyService;
+  port: number;
+}
+
+/** A request the router refused: an HTTP status, a machine code, a message. */
+export class HttpError extends Error {
+  readonly status: number;
+  readonly code: ErrorCode;
+  constructor(status: number, code: ErrorCode, message: string) {
+    super(message);
+    this.status = status;
+    this.code = code;
+  }
+}
+
+/** Refuse a request with a status, a machine code and a message. */
+export function fail(status: number, code: ErrorCode, message: string): never {
+  throw new HttpError(status, code, message);
+}
+
+/** Security headers on every response (the page loads nothing from anywhere else). */
+export function applyBaseHeaders(res: ServerResponse): void {
+  res.setHeader("X-Content-Type-Options", "nosniff");
+  res.setHeader("Referrer-Policy", "no-referrer");
+  res.setHeader("X-Frame-Options", "DENY");
+}
+
+/** Answer JSON, never cached. */
+export function sendJson(res: ServerResponse, status: number, body: unknown, extra: Record<string, string> = {}): void {
+  applyBaseHeaders(res);
+  res.writeHead(status, { "Content-Type": "application/json; charset=utf-8", "Cache-Control": "no-store", ...extra });
+  res.end(JSON.stringify(body));
+}
+
+/** Answer `{ok:false,error,code}` with the code's status. */
+export function sendError(res: ServerResponse, code: ErrorCode, error: string, status = statusFor(code)): void {
+  sendJson(res, status, { ok: false, error, code });
+}
+
+type Handler = (body: Record<string, unknown>, ctx: ApiContext) => unknown | Promise<unknown>;
+
+interface Route {
+  schema: TObject;
+  run: Handler;
+}
+
+const Empty = Type.Object({}, { additionalProperties: false });
+const TaskId = Type.String({ minLength: 1, maxLength: 200 });
+const GhNumber = Type.Integer({ minimum: 1, maximum: 1_000_000_000 });
+const NoticeText = Type.String({ maxLength: 20_000 });
+const CommentText = Type.String({ maxLength: 10_000 });
+const DialogAnswer = Type.Union([
+  Type.Object({ value: Type.String() }, { additionalProperties: false }),
+  Type.Object({ confirmed: Type.Boolean() }, { additionalProperties: false }),
+  Type.Object({ cancelled: Type.Literal(true) }, { additionalProperties: false }),
+]);
+
+const Member = Type.Union([Type.Literal("backend"), Type.Literal("designer"), Type.Literal("qa"), Type.Literal("researcher")]);
+const KnowledgeAgent = Type.Union([Type.Literal("master"), Type.Literal("designer"), Type.Literal("backend"), Type.Literal("qa")]);
+const KnowledgeFile = Type.String({ minLength: 1, maxLength: 200 });
+const KnowledgeText = Type.String({ minLength: 1, maxLength: 100_000 });
+const EntryRef = Type.Object({ text: Type.String({ minLength: 1, maxLength: 100_000 }), occurrence: Type.Integer({ minimum: 0, maximum: 100000 }) }, { additionalProperties: false });
+const ExcalidrawAgent = Type.Union([Type.Literal("master"), Type.Literal("designer"), Type.Literal("backend"), Type.Literal("qa"), Type.Literal("scout"), Type.Literal("researcher"), Type.Literal("quickfix"), Type.Literal("planner")]);
+const PlannerSeed = Type.Object({
+  issue: Type.Object({ number: Type.Integer({ minimum: 1 }), title: Type.String({ minLength: 1, maxLength: 500 }), url: Type.Optional(Type.String({ maxLength: 2000 })) }, { additionalProperties: false }),
+  body: Type.String({ maxLength: 20_000 }),
+}, { additionalProperties: false });
+
+function firstError(schema: TObject, body: unknown): string {
+  const check = Compile(schema);
+  const [first] = [...check.Errors(body ?? {})];
+  return first?.message ?? "the request does not match its schema";
+}
+
+/** Every call the server answers, by `group.action` name. */
+function buildRoutes(): Record<string, Route> {
+  const routes: Record<string, Route> = Object.create(null);
+  routes["status.get"] = { schema: Empty, run: (_body, ctx) => statusGet(ctx) };
+  routes["lobby.snapshot"] = { schema: Empty, run: (_body, ctx) => lobbySnapshot(ctx) };
+  routes["lobby.history"] = {
+    schema: Type.Object({ before: Type.Optional(Type.Number()) }, { additionalProperties: false }),
+    run: (body, ctx) => lobbyHistory(body as { before?: number }, ctx),
+  };
+  routes["lobby.send"] = {
+    schema: Type.Object({ text: Type.String({ maxLength: 20_000 }) }, { additionalProperties: false }),
+    run: (body, ctx) => lobbySend(body as { text: string }, ctx),
+  };
+  routes["lobby.abort"] = { schema: Empty, run: (_body, ctx) => lobbyAbort(ctx) };
+  routes["tasks.list"] = { schema: Empty, run: (_body, ctx) => tasksList(ctx) };
+  routes["tasks.archived"] = { schema: Empty, run: (_body, ctx) => tasksArchived(ctx) };
+  routes["tasks.get"] = {
+    schema: Type.Object({ taskId: TaskId }, { additionalProperties: false }),
+    run: (body, ctx) => tasksGet(body as { taskId: string }, ctx),
+  };
+  routes["tasks.comments"] = {
+    schema: Type.Object({ taskId: TaskId }, { additionalProperties: false }),
+    run: (body, ctx) => tasksComments(body as { taskId: string }, ctx),
+  };
+  routes["tasks.comment"] = {
+    schema: Type.Object({ taskId: TaskId, text: CommentText }, { additionalProperties: false }),
+    run: (body, ctx) => tasksComment(body as { taskId: string; text: string }, ctx),
+  };
+  routes["tasks.archive"] = {
+    schema: Type.Object({ taskId: TaskId }, { additionalProperties: false }),
+    run: (body, ctx) => tasksArchive(body as { taskId: string }, ctx),
+  };
+  routes["tasks.restore"] = {
+    schema: Type.Object({ taskId: TaskId }, { additionalProperties: false }),
+    run: (body, ctx) => tasksRestore(body as { taskId: string }, ctx),
+  };
+  routes["tasks.delete"] = {
+    schema: Type.Object({ taskId: TaskId, where: Type.Union([Type.Literal("list"), Type.Literal("archive")]) }, { additionalProperties: false }),
+    run: (body, ctx) => tasksDelete(body as { taskId: string; where: "list" | "archive" }, ctx),
+  };
+  routes["tasks.auto"] = {
+    schema: Type.Object({ taskId: TaskId, on: Type.Boolean() }, { additionalProperties: false }),
+    run: (body, ctx) => tasksAuto(body as { taskId: string; on: boolean }, ctx),
+  };
+  routes["tasks.message"] = {
+    schema: Type.Object({ taskId: TaskId, text: NoticeText }, { additionalProperties: false }),
+    run: (body, ctx) => tasksMessage(body as { taskId: string; text: string }, ctx),
+  };
+  routes["plans.get"] = {
+    schema: Type.Object({ planId: TaskId }, { additionalProperties: false }),
+    run: (body, ctx) => plansGet(body as { planId: string }, ctx),
+  };
+  routes["plans.start"] = {
+    schema: Type.Object({ planId: TaskId, where: Type.Union([Type.Literal("here"), Type.Literal("session")]), auto: Type.Optional(Type.Boolean()) }, { additionalProperties: false }),
+    run: (body, ctx) => plansStart(body as { planId: string; where: "here" | "session"; auto?: boolean }, ctx),
+  };
+  routes["plans.discard"] = {
+    schema: Type.Object({ planId: TaskId }, { additionalProperties: false }),
+    run: (body, ctx) => plansDiscard(body as { planId: string }, ctx),
+  };
+  routes["sessions.list"] = { schema: Empty, run: (_body, ctx) => sessionsList(ctx) };
+  routes["sessions.chat"] = {
+    schema: Type.Object({ key: Type.Optional(TaskId), sessionId: Type.Optional(TaskId), before: Type.Optional(Type.Number()) }, { additionalProperties: false }),
+    run: (body, ctx) => sessionsChat(body as { key?: string; sessionId?: string; before?: number }, ctx),
+  };
+  routes["sessions.start"] = {
+    schema: Type.Object({ request: Type.Optional(NoticeText), planId: Type.Optional(TaskId), auto: Type.Optional(Type.Boolean()) }, { additionalProperties: false }),
+    run: (body, ctx) => sessionsStart(body as { request?: string; planId?: string; auto?: boolean }, ctx),
+  };
+  routes["sessions.stop"] = {
+    schema: Type.Object({ key: TaskId }, { additionalProperties: false }),
+    run: (body, ctx) => sessionsStop(body as { key: string }, ctx),
+  };
+  routes["sessions.message"] = {
+    schema: Type.Object({ key: Type.Optional(TaskId), sessionId: Type.Optional(TaskId), text: NoticeText }, { additionalProperties: false }),
+    run: (body, ctx) => sessionsMessage(body as { key?: string; sessionId?: string; text: string }, ctx),
+  };
+  routes["sessions.switch"] = {
+    schema: Type.Object({ key: Type.Optional(TaskId), sessionId: Type.Optional(TaskId), claimTaskId: Type.Optional(TaskId) }, { additionalProperties: false }),
+    run: (body, ctx) => sessionsSwitch(body as { key?: string; sessionId?: string; claimTaskId?: string }, ctx),
+  };
+  routes["sessions.answer"] = {
+    schema: Type.Object({ key: TaskId, dialogId: TaskId, answer: DialogAnswer }, { additionalProperties: false }),
+    run: (body, ctx) => sessionsAnswer(body as { key: string; dialogId: string; answer: { value: string } | { confirmed: boolean } | { cancelled: true } }, ctx),
+  };
+  routes["prompts.list"] = { schema: Empty, run: (_body, ctx) => promptsList(ctx) };
+  routes["prompts.answer"] = {
+    schema: Type.Object({ id: Type.String(), answer: Type.Any() }, { additionalProperties: false }),
+    run: (body, ctx) => promptsAnswer(body as { id: string; answer: unknown }, ctx),
+  };
+  routes["prompts.dismiss"] = {
+    schema: Type.Object({ id: Type.String() }, { additionalProperties: false }),
+    run: (body, ctx) => promptsDismiss(body as { id: string }, ctx),
+  };
+  routes["planner.get"] = { schema: Empty, run: (_body, ctx) => plannerGet(ctx) };
+  routes["planner.new"] = {
+    schema: Type.Object({ seed: Type.Optional(PlannerSeed), seats: Type.Optional(Type.Array(Member, { maxItems: 4 })) }, { additionalProperties: false }),
+    run: (body, ctx) => plannerNew(body as { seed?: { issue: { number: number; title: string; url?: string }; body: string }; seats?: ("backend" | "designer" | "qa" | "researcher")[] }, ctx),
+  };
+  routes["planner.send"] = {
+    schema: Type.Object({ text: NoticeText }, { additionalProperties: false }),
+    run: (body, ctx) => plannerSend(body as { text: string }, ctx),
+  };
+  routes["planner.toggleSeat"] = {
+    schema: Type.Object({ member: Member }, { additionalProperties: false }),
+    run: (body, ctx) => plannerToggleSeat(body as { member: "backend" | "designer" | "qa" | "researcher" }, ctx),
+  };
+  routes["planner.retry"] = { schema: Empty, run: (_body, ctx) => plannerRetry(ctx) };
+  routes["planner.commentLine"] = {
+    schema: Type.Object({ line: Type.String({ minLength: 1, maxLength: 5000 }), text: CommentText }, { additionalProperties: false }),
+    run: (body, ctx) => plannerCommentLine(body as { line: string; text: string }, ctx),
+  };
+  routes["planner.answer"] = { schema: Empty, run: (_body, ctx) => plannerAnswer(ctx) };
+  routes["planner.save"] = { schema: Empty, run: (_body, ctx) => plannerSave(ctx) };
+  routes["quickfix.list"] = { schema: Empty, run: (_body, ctx) => quickfixList(ctx) };
+  routes["quickfix.submit"] = {
+    schema: Type.Object({ text: NoticeText }, { additionalProperties: false }),
+    run: (body, ctx) => quickfixSubmit(body as { text: string }, ctx),
+  };
+  routes["quickfix.cancel"] = {
+    schema: Type.Object({ id: TaskId }, { additionalProperties: false }),
+    run: (body, ctx) => quickfixCancel(body as { id: string }, ctx),
+  };
+  routes["quickfix.runAnyway"] = {
+    schema: Type.Object({ id: TaskId }, { additionalProperties: false }),
+    run: (body, ctx) => quickfixRunAnyway(body as { id: string }, ctx),
+  };
+  routes["quickfix.movedToTask"] = {
+    schema: Type.Object({ id: TaskId }, { additionalProperties: false }),
+    run: (body, ctx) => quickfixMovedToTask(body as { id: string }, ctx),
+  };
+  routes["metrics.get"] = {
+    schema: Type.Object({ groupBy: Type.Union([Type.Literal("model"), Type.Literal("model-kind")]), query: Type.Optional(Type.String({ maxLength: 500 })) }, { additionalProperties: false }),
+    run: (body, ctx) => metricsGet(body as { groupBy: "model" | "model-kind"; query?: string }, ctx),
+  };
+  routes["knowledge.files"] = { schema: Empty, run: (_body, ctx) => knowledgeFiles(ctx) };
+  routes["knowledge.open"] = {
+    schema: Type.Object({ agent: KnowledgeAgent, file: KnowledgeFile }, { additionalProperties: false }),
+    run: (body, ctx) => knowledgeOpen(body as { agent: "master" | "designer" | "backend" | "qa"; file: string }, ctx),
+  };
+  routes["knowledge.edit"] = {
+    schema: Type.Object({ agent: KnowledgeAgent, file: KnowledgeFile, ref: EntryRef, text: KnowledgeText }, { additionalProperties: false }),
+    run: (body, ctx) => knowledgeEdit(body as { agent: "master" | "designer" | "backend" | "qa"; file: string; ref: { text: string; occurrence: number }; text: string }, ctx),
+  };
+  routes["knowledge.add"] = {
+    schema: Type.Object({ agent: KnowledgeAgent, file: KnowledgeFile, ref: Type.Optional(EntryRef), text: KnowledgeText }, { additionalProperties: false }),
+    run: (body, ctx) => knowledgeAdd(body as { agent: "master" | "designer" | "backend" | "qa"; file: string; ref?: { text: string; occurrence: number }; text: string }, ctx),
+  };
+  routes["knowledge.remove"] = {
+    schema: Type.Object({ agent: KnowledgeAgent, file: KnowledgeFile, ref: EntryRef }, { additionalProperties: false }),
+    run: (body, ctx) => knowledgeRemove(body as { agent: "master" | "designer" | "backend" | "qa"; file: string; ref: { text: string; occurrence: number } }, ctx),
+  };
+  routes["knowledge.replaceFile"] = {
+    schema: Type.Object({ agent: KnowledgeAgent, file: KnowledgeFile, text: Type.String({ maxLength: 100_000 }) }, { additionalProperties: false }),
+    run: (body, ctx) => knowledgeReplaceFile(body as { agent: "master" | "designer" | "backend" | "qa"; file: string; text: string }, ctx),
+  };
+  routes["knowledge.comment"] = {
+    schema: Type.Object({ agent: KnowledgeAgent, file: KnowledgeFile, ref: EntryRef, text: Type.String({ minLength: 1, maxLength: 2000 }) }, { additionalProperties: false }),
+    run: (body, ctx) => knowledgeComment(body as { agent: "master" | "designer" | "backend" | "qa"; file: string; ref: { text: string; occurrence: number }; text: string }, ctx),
+  };
+  routes["knowledge.unnote"] = {
+    schema: Type.Object({ id: TaskId }, { additionalProperties: false }),
+    run: (body, ctx) => knowledgeUnnote(body as { id: string }, ctx),
+  };
+  routes["excalidraw.list"] = { schema: Empty, run: (_body, ctx) => excalidrawList(ctx) };
+  routes["excalidraw.add"] = {
+    schema: Type.Object({ link: Type.String({ minLength: 1, maxLength: 2000 }), name: Type.Optional(Type.String({ maxLength: 40 })) }, { additionalProperties: false }),
+    run: (body, ctx) => excalidrawAdd(body as { link: string; name?: string }, ctx),
+  };
+  routes["excalidraw.create"] = {
+    schema: Type.Object({ name: Type.Optional(Type.String({ maxLength: 40 })) }, { additionalProperties: false }),
+    run: (body, ctx) => excalidrawCreate(body as { name?: string }, ctx),
+  };
+  routes["excalidraw.remove"] = {
+    schema: Type.Object({ id: TaskId }, { additionalProperties: false }),
+    run: (body, ctx) => excalidrawRemove(body as { id: string }, ctx),
+  };
+  routes["excalidraw.rename"] = {
+    schema: Type.Object({ id: TaskId, name: Type.String({ maxLength: 40 }) }, { additionalProperties: false }),
+    run: (body, ctx) => excalidrawRename(body as { id: string; name: string }, ctx),
+  };
+  routes["excalidraw.toggleAgent"] = {
+    schema: Type.Object({ id: TaskId, agent: ExcalidrawAgent }, { additionalProperties: false }),
+    run: (body, ctx) => excalidrawToggleAgent(body as { id: string; agent: "master" | "designer" | "backend" | "qa" | "scout" | "researcher" | "quickfix" | "planner" }, ctx),
+  };
+  routes["excalidraw.toggleAll"] = {
+    schema: Type.Object({ id: TaskId }, { additionalProperties: false }),
+    run: (body, ctx) => excalidrawToggleAll(body as { id: string }, ctx),
+  };
+  routes["excalidraw.toggleContribute"] = {
+    schema: Type.Object({ id: TaskId }, { additionalProperties: false }),
+    run: (body, ctx) => excalidrawToggleContribute(body as { id: string }, ctx),
+  };
+  routes["excalidraw.check"] = {
+    schema: Type.Object({ id: TaskId }, { additionalProperties: false }),
+    run: (body, ctx) => excalidrawCheck(body as { id: string }, ctx),
+  };
+  routes["excalidraw.reveal"] = {
+    schema: Type.Object({ id: TaskId }, { additionalProperties: false }),
+    run: (body, ctx) => excalidrawReveal(body as { id: string }, ctx),
+  };
+  routes["git.pulls"] = {
+    schema: Type.Object({ refresh: Type.Optional(Type.Boolean()) }, { additionalProperties: false }),
+    run: (body, ctx) => gitPulls(body as { refresh?: boolean }, ctx),
+  };
+  routes["git.pull"] = {
+    schema: Type.Object({ number: GhNumber }, { additionalProperties: false }),
+    run: (body, ctx) => gitPull(body as { number: number }, ctx),
+  };
+  routes["git.review"] = {
+    schema: Type.Object({ number: GhNumber, focus: Type.Optional(Type.String({ maxLength: 2000 })) }, { additionalProperties: false }),
+    run: (body, ctx) => gitReview(body as { number: number; focus?: string }, ctx),
+  };
+  routes["git.cancelReview"] = {
+    schema: Type.Object({ number: GhNumber }, { additionalProperties: false }),
+    run: (body, ctx) => gitCancelReview(body as { number: number }, ctx),
+  };
+  routes["git.jev"] = {
+    schema: Type.Object({ number: GhNumber }, { additionalProperties: false }),
+    run: (body, ctx) => gitJev(body as { number: number }, ctx),
+  };
+  routes["issues.list"] = {
+    schema: Type.Object({ refresh: Type.Optional(Type.Boolean()) }, { additionalProperties: false }),
+    run: (body, ctx) => issuesList(body as { refresh?: boolean }, ctx),
+  };
+  routes["issues.get"] = {
+    schema: Type.Object({ number: GhNumber }, { additionalProperties: false }),
+    run: (body, ctx) => issuesGet(body as { number: number }, ctx),
+  };
+  routes["issues.create"] = {
+    schema: Type.Object({ text: Type.String({ maxLength: 20_000 }) }, { additionalProperties: false }),
+    run: (body, ctx) => issuesCreate(body as { text: string }, ctx),
+  };
+  routes["settings.get"] = { schema: Empty, run: (_body, ctx) => settingsGet(ctx) };
+  routes["settings.set"] = {
+    // The patch's shape is the normaliser's job (`resolveConfig`); only a plain object is required here.
+    schema: Type.Object({ patch: Type.Object({}, { additionalProperties: true }) }, { additionalProperties: false }),
+    run: (body, ctx) => settingsSet(body as { patch: Record<string, unknown> }, ctx),
+  };
+  return routes;
+}
+
+const ROUTES = buildRoutes();
+
+/** Whether the router knows a call (defined names only; never inherited ones). */
+export function isKnownCall(name: string): boolean {
+  return Object.hasOwn(ROUTES, name);
+}
+
+/**
+ * Run `POST /api/<name>` with an already-parsed body. Throws `HttpError` for
+ * refusals (unknown call, a body that is no object, a schema mismatch, or a
+ * handler's own refusal); anything else is a 500.
+ */
+export async function routeApiCall(name: string, body: unknown, ctx: ApiContext): Promise<unknown> {
+  const route = Object.hasOwn(ROUTES, name) ? ROUTES[name] : undefined;
+  if (!route) fail(404, "not_found", `no call ${name}`);
+  if (!body || typeof body !== "object" || Array.isArray(body)) fail(400, "bad_request", "the body must be a JSON object");
+  const checked = route as Route;
+  if (!Compile(checked.schema).Check(body)) fail(400, "bad_request", firstError(checked.schema, body));
+  const result = await checked.run(body as Record<string, unknown>, ctx);
+  const notice = noticeText(result);
+  if (notice) pushNotice(notice);
+  return result;
+}
+
+/** Read the call name from `POST /api/<group>.<action>` (undefined for anything else). */
+export function callName(url: URL): string | undefined {
+  const path = url.pathname;
+  if (!path.startsWith("/api/")) return undefined;
+  const name = path.slice("/api/".length);
+  return /^[a-z]+\.[a-zA-Z]+$/.test(name) ? name : undefined;
+}
+
+export type { ApiName };

package/src/webui/api/issues.ts

@@ -0,0 +1,50 @@
+/**
+ * The Issues tab over HTTP: the open issues, one issue with its comments, and
+ * filing a new one, all through the lobby's `IssuesState` (so `gh` owns
+ * authentication and the repository). With `lobby.issues` off every call is
+ * a 404, like the tab being absent from the terminal.
+ */
+import type { IssueDetailInfo, IssueInfo, IssuesList } from "../protocol.ts";
+import type { ApiContext } from "./index.ts";
+import { fail } from "./index.ts";
+import { ghRefusal } from "./gh-error.ts";
+
+function requireIssues(ctx: ApiContext): void {
+  if (!ctx.service.issuesEnabled()) fail(404, "not_found", "issues are off (lobby.issues)");
+}
+
+function issueInfo(issue: IssueInfo): IssueInfo {
+  return { ...issue, labels: [...issue.labels] };
+}
+
+/** The open issues; read from `gh` the first time or when `refresh` asks (a failure is not retried until asked). */
+export async function issuesList(body: { refresh?: boolean }, ctx: ApiContext): Promise<IssuesList> {
+  requireIssues(ctx);
+  const state = ctx.service.issues;
+  if (body.refresh || (!state.loaded && !state.error)) {
+    state.details.clear();
+    await state.refresh();
+  }
+  return { issues: state.issues.map(issueInfo), loading: state.loading, loaded: state.loaded, ...(state.error ? { error: state.error } : {}) };
+}
+
+/** One issue with its description and comments. */
+export async function issuesGet(body: { number: number }, ctx: ApiContext): Promise<{ issue: IssueDetailInfo }> {
+  requireIssues(ctx);
+  const detail = await ctx.service.issues.detail(body.number);
+  if (!detail) ghRefusal(ctx.service.issues.error, `issue #${body.number}`);
+  const found = detail!;
+  return { issue: { ...issueInfo(found), body: found.body, ...(found.state ? { state: found.state } : {}), comments: found.comments.map((comment) => ({ ...comment })) } };
+}
+
+/** File an issue: the first line is the title, the rest the body. */
+export async function issuesCreate(body: { text: string }, ctx: ApiContext): Promise<{ notice: string }> {
+  requireIssues(ctx);
+  if (!body.text.trim()) return { notice: "type something first" };
+  const state = ctx.service.issues;
+  state.notice = undefined;
+  state.error = undefined;
+  await state.create(body.text);
+  if (!state.notice) fail(500, "failed", state.error ?? "could not file the issue");
+  return { notice: state.notice! };
+}

package/src/webui/api/knowledge.ts

@@ -0,0 +1,79 @@
+/**
+ * The Knowledge tab over HTTP: every agent's files, one file read as entries
+ * with its notes, and the tab's edits (edit, add, delete, whole-file replace,
+ * comment, take a note back). Actions answer with the same notice text the
+ * terminal shows; an edit whose entry changed on disk since it was drawn is
+ * refused with a 409, like the tab's reload hint.
+ */
+import type { KnowledgeAgent } from "../../knowledge/paths.ts";
+import type { EntryRef } from "../../lobby/knowledge.ts";
+import type { KnowledgeFileInfo, KnowledgeViewData } from "../protocol.ts";
+import type { ApiContext } from "./index.ts";
+import { fail } from "./index.ts";
+
+/** The terminal's stale-entry refusal, as `KnowledgeBook` words it. */
+function isStale(notice: string): boolean {
+  return notice.startsWith("that entry changed on disk");
+}
+
+/** Refuse a stale entry with the terminal's own words. */
+function stale(notice: string): never {
+  fail(409, "conflict", notice);
+}
+
+interface FileBody {
+  agent: KnowledgeAgent;
+  file: string;
+}
+
+interface RefBody extends FileBody {
+  ref: EntryRef;
+}
+
+/** Every agent's files with their size and note counts, in tab order. */
+export function knowledgeFiles(ctx: ApiContext): { files: KnowledgeFileInfo[] } {
+  return { files: ctx.service.knowledge.files() };
+}
+
+/** One file as entries with their notes. */
+export function knowledgeOpen(body: FileBody, ctx: ApiContext): { view: KnowledgeViewData } {
+  return { view: ctx.service.knowledge.open(body.agent, body.file) };
+}
+
+/** Replace one entry with `text`, exactly as written. */
+export function knowledgeEdit(body: RefBody & { text: string }, ctx: ApiContext): { notice: string } {
+  const notice = ctx.service.knowledge.edit(body.agent, body.file, body.ref, body.text);
+  if (isStale(notice)) stale(notice);
+  return { notice };
+}
+
+/** Add a bullet after an entry (at the end when there is none). */
+export function knowledgeAdd(body: FileBody & { ref?: EntryRef; text: string }, ctx: ApiContext): { notice: string } {
+  const notice = ctx.service.knowledge.add(body.agent, body.file, body.ref, body.text);
+  if (isStale(notice)) stale(notice);
+  return { notice };
+}
+
+/** Delete an entry, and the notes on it. */
+export function knowledgeRemove(body: RefBody, ctx: ApiContext): { notice: string } {
+  const notice = ctx.service.knowledge.remove(body.agent, body.file, body.ref);
+  if (isStale(notice)) stale(notice);
+  return { notice };
+}
+
+/** Replace a whole file. */
+export function knowledgeReplaceFile(body: FileBody & { text: string }, ctx: ApiContext): { notice: string } {
+  return { notice: ctx.service.knowledge.replaceFile(body.agent, body.file, body.text) };
+}
+
+/** Leave a note on an entry. */
+export function knowledgeComment(body: RefBody & { text: string }, ctx: ApiContext): { notice: string } {
+  const notice = ctx.service.knowledge.comment(body.agent, body.file, body.ref, body.text);
+  if (isStale(notice)) stale(notice);
+  return { notice };
+}
+
+/** Take a note back. */
+export function knowledgeUnnote(body: { id: string }, ctx: ApiContext): { notice: string } {
+  return { notice: ctx.service.knowledge.unnote(body.id) };
+}