@songsid/agend 2.3.0-beta.19 → 2.3.0-beta.20

package/dist/web-api.js

@@ -12,6 +12,7 @@ import { checkOwnerCss, ownerCssAssetRefs } from "./web-owner-css.js";
 import { canonicalText } from "./web-theme.js";
 import { EFFECT_WIRE_LIMIT } from "./web-effect-upload.js";
 import { gatewayRequestContext } from "./web-request-context.js";
+import { crossInstanceVisibility } from "./cross-instance-notice.js";
 import { permitWebContinuation } from "./web-continuation.js";
 /**
  * Web UI HTTP API handler.
@@ -30,6 +31,7 @@ import { fileURLToPath } from "node:url";
 import { CreateInstanceArgs, CreateScheduleArgs, UpdateScheduleArgs, validateArgs } from "./outbound-schemas.js";
 import { scheduleView } from "./web-schedules.js";
 import { DEFAULT_SCHEDULER_CONFIG } from "./scheduler/index.js";
+import { CARD_PRIORITIES, CARD_SIZES, CARD_STATUSES, TaskBoardError } from "./scheduler/task-board.js";
 import { readStatuslineModel, resolveInstanceContext } from "./topic-commands.js";
 import { z } from "zod";
 import { evaluateWebRequest, isPassiveWebRead, isSecureRequest, isWebRequestAuthorized, WEB_TOKEN_INVALID_MESSAGE } from "./web-auth.js";
@@ -45,6 +47,8 @@ import { authorizeExplicitInstanceRemoval } from "./instance-removal.js";
 import { measureSyncWork } from "./sync-work-attribution.js";
 import { resolveTz } from "./tz-utils.js";
 import { filesPlayInChat } from "./web-effect.js";
+import { QUERY_MAX_CHARS, RESULT_MAX, SEARCH_SOURCES } from "./search/search-store.js";
+import { xmsgShown } from "./search/search-docs.js";
 // ── Strict public-facing schemas ────────────────────────────────────────────
 // web-api endpoints must reject unknown fields so the dashboard cannot inject
 // internal-only flags that would reach handleCreate/scheduler/config writers.
@@ -59,11 +63,70 @@ const TaskUpdateSchema = z.object({
     action: z.enum(["claim", "complete", "update"]).optional(),
     assignee: z.string().max(128).optional(),
     result: z.string().max(MAX_TEXT).optional(),
-    status: z.string().max(64).optional(),
+    // A status the task board knows: each carries its rules now (scheduler/task-board.ts).
+    status: z.enum(CARD_STATUSES).optional(),
     title: z.string().max(512).optional(),
     description: z.string().max(MAX_TEXT).optional(),
     priority: z.string().max(64).optional(),
 }).strict();
+// The task board (scheduler/task-board.ts). Coarse bounds here; the board checks each field's own limit.
+const BOARD_TEXT = 8_192;
+const CardRef = z.string().min(1).max(64);
+/** Who handed a card out: an instance, the person writing ({ kind: "person" }), or nobody. */
+const DispatcherSchema = z.union([z.object({ kind: z.literal("instance"), name: z.string().min(1).max(128) }).strict(), z.object({ kind: z.literal("person") }).strict()]).nullable();
+const CardCreateSchema = z.object({
+    kind: z.enum(["main", "sub"]).optional(),
+    project: z.union([z.number().int(), z.string().max(256)]).nullable().optional(),
+    parent: CardRef.nullable().optional(),
+    title: z.string().max(512),
+    goal: z.string().max(BOARD_TEXT).optional(),
+    scope: z.string().max(BOARD_TEXT).optional(),
+    acceptance: z.array(z.string().max(1024)).max(50).optional(),
+    context: z.string().max(BOARD_TEXT).optional(),
+    size: z.enum(CARD_SIZES).nullable().optional(),
+    priority: z.enum(CARD_PRIORITIES).optional(),
+    dependsOn: z.array(CardRef).max(50).optional(),
+    assignee: z.string().max(128).nullable().optional(),
+    dispatcher: DispatcherSchema.optional(),
+    needsReview: z.boolean().optional(),
+}).strict();
+const CardPatchSchema = z.object({
+    version: z.number().int().optional(),
+    title: z.string().max(512).optional(),
+    goal: z.string().max(BOARD_TEXT).optional(),
+    scope: z.string().max(BOARD_TEXT).optional(),
+    context: z.string().max(BOARD_TEXT).optional(),
+    state: z.string().max(BOARD_TEXT).optional(),
+    result: z.string().max(BOARD_TEXT).optional(),
+    blockedReason: z.string().max(BOARD_TEXT).optional(),
+    size: z.enum(CARD_SIZES).nullable().optional(),
+    priority: z.enum(CARD_PRIORITIES).optional(),
+    assignee: z.string().max(128).nullable().optional(),
+    dispatcher: DispatcherSchema.optional(),
+    needsReview: z.boolean().optional(),
+    dependsOn: z.array(CardRef).max(50).optional(),
+    acceptance: z.array(z.string().max(1024)).max(50).optional(),
+    addAcceptance: z.array(z.string().max(1024)).max(50).optional(),
+    check: z.array(z.number().int()).max(50).optional(),
+    uncheck: z.array(z.number().int()).max(50).optional(),
+    projectId: z.number().int().nullable().optional(),
+    log: z.string().max(BOARD_TEXT).optional(),
+    comment: z.string().max(MAX_TEXT).optional(),
+}).strict();
+const CardMoveSchema = z.object({
+    to: z.enum(CARD_STATUSES),
+    reason: z.string().max(BOARD_TEXT).optional(),
+    result: z.string().max(BOARD_TEXT).optional(),
+    comment: z.string().max(MAX_TEXT).optional(),
+    version: z.number().int().optional(),
+}).strict();
+const CardReorderSchema = z.object({ after: CardRef.nullable().optional(), before: CardRef.nullable().optional() }).strict();
+const ProjectCreateSchema = z.object({ name: z.string().max(256), description: z.string().max(BOARD_TEXT).optional() }).strict();
+const ProjectPatchSchema = z.object({
+    name: z.string().max(256).optional(),
+    description: z.string().max(BOARD_TEXT).optional(),
+    archived: z.boolean().optional(),
+}).strict();
 const TeamCreateSchema = z.object({
     name: z.string().min(1).max(128).regex(/^[A-Za-z0-9._-]+$/),
     members: z.array(z.string().min(1).max(256)).min(1).max(256),
@@ -176,10 +239,19 @@ async function parseBody(req) {
 }
 /** Send JSON response. */
 function json(res, status, data) {
+    jsonText(res, status, JSON.stringify(data));
+}
+/** A JSON answer already serialized (a body kept for reuse). */
+function jsonText(res, status, body) {
     res.setHeader("Content-Type", "application/json");
     res.writeHead(status);
-    res.end(JSON.stringify(data));
+    res.end(body);
 }
+/**
+ * #2296: the last dashboard board read, serialized, per board: its key (revision, done=all, minute) and body. One per
+ * board (the newest revision replaces the previous), so it holds one board's JSON at most.
+ */
+const boardBodies = new WeakMap();
 /**
  * #1630 (#1635 review): an answer that waited on something (a list, a download) is sent only if the request is still
  * allowed — the session not revoked meanwhile, a public link's exposure still current. Otherwise 401, and nothing.
@@ -1048,6 +1120,57 @@ function webAuthorityOf(req, url, ctx, instance) {
  * header token; null when nothing does any more (the gate also refuses a public link that is no longer the current
  * one). Equal before and after an await: the same admission still holds. Never touches the session.
  */
+/** #2293: an admin's admission — the header token or an admin session — else null (a guest's or a read-only session's). */
+function adminAdmissionOf(req, url, ctx) {
+    const v = evaluateWebRequest(req, url, ctx.webToken ?? null, ctx.webSessions, { touch: false });
+    if (v.kind !== "allow" || (v.via === "session" && v.session.tier !== "admin"))
+        return null;
+    return admissionOf(req, url, ctx);
+}
+const SEARCH_LIMIT_DEFAULT = 50;
+/**
+ * #2293: GET /ui/search's parameters: q (1–QUERY_MAX_CHARS), instance (repeated), team (its members join `instance`),
+ * source (repeated: chat, xmsg, task), since / until (epoch ms), mine=1, limit (1–RESULT_MAX).
+ */
+function parseSearchQuery(url, ctx) {
+    const p = url.searchParams;
+    const q = (p.get("q") ?? "").trim();
+    if (!q || q.length > QUERY_MAX_CHARS)
+        return { error: `q required (1-${QUERY_MAX_CHARS} chars)` };
+    const instances = new Set(p.getAll("instance").filter(n => n.length > 0 && n.length <= 128));
+    const team = p.get("team");
+    if (team) {
+        const def = ctx.fleetConfig?.teams && Object.hasOwn(ctx.fleetConfig.teams, team) ? ctx.fleetConfig.teams[team] : undefined;
+        if (!def)
+            return { error: "unknown team" };
+        for (const member of def.members ?? [])
+            instances.add(member);
+        if (!instances.size)
+            return { error: "team has no members" };
+    }
+    const sources = p.getAll("source");
+    if (sources.some(s => !SEARCH_SOURCES.includes(s)))
+        return { error: `source must be one of: ${SEARCH_SOURCES.join(", ")}` };
+    const time = (name) => {
+        const raw = p.get(name);
+        if (raw === null || raw === "")
+            return undefined;
+        const n = Number(raw);
+        return Number.isSafeInteger(n) && n >= 0 ? n : null;
+    };
+    const since = time("since"), until = time("until");
+    if (since === null || until === null)
+        return { error: "since/until must be epoch milliseconds" };
+    const limitRaw = p.get("limit");
+    const limit = limitRaw === null ? SEARCH_LIMIT_DEFAULT : Number(limitRaw);
+    if (!Number.isInteger(limit) || limit < 1 || limit > RESULT_MAX)
+        return { error: `limit must be 1-${RESULT_MAX}` };
+    return {
+        filters: { q, limit, ...(instances.size ? { instances: [...instances] } : {}), ...(sources.length ? { sources: sources } : {}),
+            ...(since !== undefined ? { since } : {}), ...(until !== undefined ? { until } : {}) },
+        mine: p.get("mine") === "1",
+    };
+}
 function admissionOf(req, url, ctx) {
     const gateway = gatewayRequestContext(req);
     const v = evaluateWebRequest(req, url, ctx.webToken ?? null, ctx.webSessions, { touch: false });
@@ -1063,6 +1186,61 @@ function webPersonOr401(req, res, url, ctx) {
         json(res, 401, { error: WEB_TOKEN_INVALID_MESSAGE });
     return p;
 }
+/**
+ * Who a dashboard request acts as on the task board. The person only through a signed-in local session: the header
+ * token is the CLI's or a script's (any agent on this machine can read the token file), and the temporary public link
+ * carries no verified authority (docs/web-dashboard.md) — either is a script, held to the rules an instance is held to,
+ * so neither confirms work waiting for the person.
+ */
+function boardActor(req, url, ctx, p) {
+    if (gatewayRequestContext(req))
+        return { kind: "script", name: "public-link" };
+    const v = evaluateWebRequest(req, url, ctx.webToken ?? null, ctx.webSessions, { touch: false });
+    return v.kind === "allow" && v.via === "session" ? { kind: "person", name: p.name } : { kind: "script", name: "web-token" };
+}
+/**
+ * A board refusal as the dashboard reads it: the board's sentence, its code and the status that fits, and — when the
+ * person can meet it — the key and values the page says it with in its own language.
+ */
+function boardError(res, err) {
+    if (res.headersSent)
+        return;
+    if (err instanceof TaskBoardError) {
+        const status = err.code === "not_found" ? 404 : err.code === "forbidden" ? 403 : err.code === "conflict" ? 409 : 400;
+        json(res, status, { error: err.message, code: err.code, ...(err.key ? { key: err.key, args: err.args } : {}) });
+        return;
+    }
+    json(res, 400, { error: err.message });
+}
+/**
+ * One board write from the dashboard: the body read and checked, the request still allowed, the person asked for
+ * again now the body is in (#1827), then the write as that person. The board's own routes take a signed-in session
+ * only (instances use their task tool, scripts the old /ui/tasks routes).
+ */
+function boardWrite(req, res, url, ctx, board, schema, write) {
+    void (async () => {
+        try {
+            const body = await parseBody(req);
+            if (!permitWebContinuation(req, res, ctx))
+                return;
+            const parsed = parseOrReject(schema, body, res);
+            if (!parsed)
+                return;
+            const person = webPersonOr401(req, res, url, ctx);
+            if (!person)
+                return;
+            const actor = boardActor(req, url, ctx, person);
+            if (actor.kind !== "person") {
+                json(res, 403, { error: "The task board takes changes from a signed-in dashboard", code: "forbidden", key: "signed_in_only" });
+                return;
+            }
+            json(res, 200, write(parsed, actor));
+        }
+        catch (err) {
+            boardError(res, err);
+        }
+    })();
+}
 /** #1827: what the page's profile card reads — the name they chose (or null), the one in use, and how agents know them. */
 function profileBody(p) {
     return { name: p.set ? p.name : null, shown: p.name, id: p.userId, bound: p.bound, ...(p.platformName !== undefined ? { platform_name: p.platformName } : {}) };
@@ -2321,6 +2499,11 @@ export function handleWebRequest(req, res, url, ctx) {
         json(res, 200, { tasks });
         return true;
     }
+    // #2246: the public link writes no task — the old list's create and update are board writes now (see below).
+    if (method === "POST" && (path === "/ui/tasks" || /^\/ui\/tasks\/[^/]+$/.test(path)) && gatewayRequestContext(req)) {
+        json(res, 403, { error: "task_board_not_over_public_link", code: "forbidden", key: "not_over_public_link" });
+        return true;
+    }
     if (method === "POST" && path === "/ui/tasks") {
         if (!ctx.scheduler) {
             json(res, 500, { error: "Scheduler not initialized" });
@@ -2343,7 +2526,7 @@ export function handleWebRequest(req, res, url, ctx) {
                     priority: parsed.priority,
                     assignee: parsed.assignee,
                     created_by: person.name, // #1827
-                });
+                }, boardActor(req, url, ctx, person));
                 json(res, 200, task);
             }
             catch (err) {
@@ -2352,15 +2535,144 @@ export function handleWebRequest(req, res, url, ctx) {
         })();
         return true;
     }
+    // ── Task board (scheduler/task-board.ts) ──────────────
+    // Reads are the session's; every write is the signed-in person's, through the same rules an instance's tools use.
+    if (path === "/ui/tasks/board" || path === "/ui/tasks/search" || path.startsWith("/ui/tasks/cards") || path.startsWith("/ui/tasks/projects")) {
+        const board = ctx.scheduler?.db.board;
+        if (!board) {
+            json(res, 503, { error: "The task board is not available" });
+            return true;
+        }
+        // The temporary public link reads the board and changes nothing on it: confirming, sending back, cancelling and
+        // assigning are the person's authority, which the public link never carries (docs/web-dashboard.md).
+        const gateway = gatewayRequestContext(req);
+        if (gateway && method !== "GET") {
+            json(res, 403, { error: "task_board_not_over_public_link", code: "forbidden", key: "not_over_public_link" });
+            return true;
+        }
+        // …nor shows the cards of instances kept out of sight (cross_instance_visibility: hidden).
+        const fleet = ctx.fleetConfig;
+        const hiddenName = (n) => !!gateway && typeof n === "string" && !!n && !!ctx.fleetConfig?.instances?.[n] && crossInstanceVisibility(fleet, n) === "hidden";
+        const hidden = (c) => [c.assignee, c.createdBy, c.dispatcher?.name].some(hiddenName);
+        // #2303 review: what a visible card shows of the cards around it follows the same rule — its children, its main
+        // task (a search hit's too) — and so do the words and the history a hidden instance left on it.
+        // …and a hidden instance's words on a visible card are not counted, named or found there (#2304 review).
+        const scope = { leaveOutAuthors: gateway ? Object.keys(ctx.fleetConfig?.instances ?? {}).filter(hiddenName) : [] };
+        const hiddenRef = (ref) => { const c = ref ? board.findCard(ref) : undefined; return !!c && hidden(c); };
+        const mentionsHidden = (v) => (typeof v === "string" ? hiddenName(v) : !!v && typeof v === "object" && Object.values(v).some(mentionsHidden));
+        const shown = (d) => !gateway ? d : {
+            ...d,
+            parent: d.card.parentId && hiddenRef(d.card.parentId) ? null : d.parent,
+            children: d.children.filter((c) => !hidden(c)),
+            comments: d.comments.filter((e) => !hiddenName(e.author)),
+            logs: d.logs.filter((e) => !hiddenName(e.author)),
+            history: d.history.filter((e) => !hiddenName(e.actor) && !mentionsHidden(e.data)),
+        };
+        const card = /^\/ui\/tasks\/cards\/([^/]+)(?:\/(move|reorder))?$/.exec(path);
+        const project = /^\/ui\/tasks\/projects\/(\d+)$/.exec(path);
+        try {
+            const ref = card ? decodeURIComponent(card[1]) : "";
+            if (method === "GET" && path === "/ui/tasks/board") {
+                // A page that has this revision already is told so, not sent the board again.
+                const rev = board.revision();
+                if (url.searchParams.get("rev") === String(rev)) {
+                    json(res, 200, { rev, unchanged: true });
+                    return true;
+                }
+                const allDone = url.searchParams.get("done") === "all";
+                // #2296: every open Tasks tab reads the board again after each change; on the dashboard they all get the same
+                // board for a revision, so it is built once per (revision, done=all, minute) — the minute for the 14-day
+                // window. The public link's reads are filtered per request (hidden instances) and are built each time.
+                const key = gateway ? null : `${rev}:${allDone ? 1 : 0}:${Math.floor(Date.now() / 60_000)}`;
+                const kept = key ? boardBodies.get(board) : undefined;
+                if (kept && kept.key === key) {
+                    jsonText(res, 200, kept.body);
+                    return true;
+                }
+                const cards = board.boardCards(undefined, allDone).filter((c) => !hidden(c));
+                const body = JSON.stringify({ rev, cards: board.views(cards, scope), projects: board.listProjects(true), stats: board.projectStats() });
+                if (key)
+                    boardBodies.set(board, { key, body });
+                jsonText(res, 200, body);
+                return true;
+            }
+            if (method === "GET" && path === "/ui/tasks/search") {
+                const names = new Map(board.listProjects(true).map((p) => [p.id, p.name]));
+                const hits = board.search(url.searchParams.get("q") ?? "", Number(url.searchParams.get("limit")) || 20, scope).filter((h) => !hidden(h.card));
+                const views = board.views(hits.map((h) => h.card), scope);
+                const results = hits.map(({ card: c, match }, i) => ({
+                    card: views[i],
+                    match,
+                    project: c.projectId === null ? null : names.get(c.projectId) ?? null,
+                    parentTitle: c.parent && !hiddenRef(c.parent) ? board.findCard(c.parent)?.title ?? null : null,
+                }));
+                json(res, 200, { results });
+                return true;
+            }
+            if (method === "GET" && card && !card[2]) {
+                const found = board.getCard(ref);
+                if (hidden(found)) {
+                    json(res, 404, { error: "no such card", code: "not_found" });
+                    return true;
+                }
+                json(res, 200, shown(board.detail(ref, scope)));
+                return true;
+            }
+            if (method === "POST" && path === "/ui/tasks/cards") {
+                boardWrite(req, res, url, ctx, board, CardCreateSchema, (spec, person) => {
+                    const { cards, said } = board.createCards(person, { cards: [spec] });
+                    return { card: board.view(cards[0]), notes: said };
+                });
+                return true;
+            }
+            if (method === "POST" && card) {
+                if (card[2] === "move") {
+                    boardWrite(req, res, url, ctx, board, CardMoveSchema, ({ to, ...move }, person) => {
+                        const { card: moved, said } = board.moveCard(person, ref, to, move);
+                        return { card: board.view(moved), notes: said };
+                    });
+                }
+                else if (card[2] === "reorder") {
+                    boardWrite(req, res, url, ctx, board, CardReorderSchema, ({ after, before }, person) => ({ card: board.view(board.reorder(person, ref, after ?? null, before ?? null)) }));
+                }
+                else {
+                    boardWrite(req, res, url, ctx, board, CardPatchSchema, (patch, person) => {
+                        const { card: updated, said } = board.updateCard(person, ref, patch);
+                        return { card: board.view(updated), notes: said };
+                    });
+                }
+                return true;
+            }
+            if (method === "POST" && path === "/ui/tasks/projects") {
+                boardWrite(req, res, url, ctx, board, ProjectCreateSchema, (input, person) => ({ project: board.createProject(person, input) }));
+                return true;
+            }
+            if (method === "POST" && project) {
+                boardWrite(req, res, url, ctx, board, ProjectPatchSchema, (patch, person) => ({ project: board.updateProject(person, Number(project[1]), patch) }));
+                return true;
+            }
+        }
+        catch (err) {
+            // A malformed %-escape in the card's address is the caller's mistake, not the server's.
+            if (err instanceof URIError) {
+                json(res, 400, { error: "bad card reference", code: "invalid" });
+                return true;
+            }
+            boardError(res, err);
+            return true;
+        }
+        json(res, 404, { error: "Not found" });
+        return true;
+    }
     const taskMatch = path.match(/^\/ui\/tasks\/(.+)$/);
     if (method === "POST" && taskMatch) {
         if (!ctx.scheduler) {
             json(res, 500, { error: "Scheduler not initialized" });
             return true;
         }
-        const id = decodeURIComponent(taskMatch[1]);
         (async () => {
             try {
+                const id = decodeURIComponent(taskMatch[1]);
                 const body = await parseBody(req);
                 if (!permitWebContinuation(req, res, ctx))
                     return;
@@ -2368,19 +2680,22 @@ export function handleWebRequest(req, res, url, ctx) {
                 if (!parsed)
                     return;
                 let result;
+                // #1827: the person, who is also the default assignee of a claim; the task board's review gate needs to know
+                // a person (not an instance) made the move.
+                const person = webPersonOr401(req, res, url, ctx);
+                if (!person)
+                    return;
+                const by = boardActor(req, url, ctx, person);
                 if (parsed.action === "claim") {
-                    const person = parsed.assignee ? null : webPersonOr401(req, res, url, ctx); // #1827: the default is the person
-                    if (!parsed.assignee && !person)
-                        return;
-                    result = ctx.scheduler.db.claimTask(id, parsed.assignee || person.name);
+                    result = ctx.scheduler.db.claimTask(id, parsed.assignee || person.name, by);
                 }
                 else if (parsed.action === "complete") {
-                    result = ctx.scheduler.db.completeTask(id, parsed.result);
+                    result = ctx.scheduler.db.completeTask(id, parsed.result, by);
                 }
                 else {
                     // Strip action before passing remaining fields to updateTask
                     const { action: _a, ...rest } = parsed;
-                    result = ctx.scheduler.db.updateTask(id, rest);
+                    result = ctx.scheduler.db.updateTask(id, rest, by);
                 }
                 json(res, 200, result);
             }
@@ -2508,6 +2823,89 @@ export function handleWebRequest(req, res, url, ctx) {
         }
         return true;
     }
+    // #2293: global search — an admin's only: the header token or an admin session. Never over the public link (the gateway
+    // does not list it either), never a guest (not in GUEST_ROUTES). Asked on arrival and again before the answer is sent.
+    if (method === "GET" && (path === "/ui/search" || path === "/ui/search/context")) {
+        const refusal = () => {
+            if (gatewayRequestContext(req))
+                return [404, "search_not_over_public_link"];
+            if (guestRequestOf(req))
+                return [403, "guest_forbidden"];
+            if (ctx.fleetConfig?.web?.search?.enabled === false || !ctx.searchIndex || ctx.searchIndex.status() === "unavailable")
+                return [404, "search_unavailable"];
+            return null;
+        };
+        const first = refusal();
+        if (first) {
+            json(res, first[0], { error: first[1] });
+            return true;
+        }
+        const admitted = adminAdmissionOf(req, url, ctx);
+        if (!admitted) {
+            json(res, 401, { error: WEB_TOKEN_INVALID_MESSAGE });
+            return true;
+        }
+        const index = ctx.searchIndex;
+        // cross_instance_visibility "hidden" (fleet-traffic's rule): a message to or from such a name is not found.
+        const visibility = () => ctx.searchVisibility?.() ?? { hidden: [] };
+        const shown = (doc) => xmsgShown(doc, visibility());
+        const finish = (status, body) => {
+            const now = refusal();
+            if (now)
+                return json(res, now[0], { error: now[1] });
+            if (adminAdmissionOf(req, url, ctx) !== admitted)
+                return json(res, 401, { error: WEB_TOKEN_INVALID_MESSAGE });
+            json(res, status, body);
+        };
+        const failed = (reason) => finish(reason === "timeout" || reason === "busy" ? 503 : 404, { error: `search_${reason}` });
+        if (path === "/ui/search/context") {
+            const key = url.searchParams.get("key") ?? "";
+            if (!key || key.length > 300) {
+                json(res, 400, { error: "key required" });
+                return true;
+            }
+            void index.context(key).then(r => {
+                if (!r.ok)
+                    return failed(r.reason);
+                const doc = r.value?.doc;
+                // A message to or from an instance that is hidden now is not shown, as in the search itself.
+                if (!doc || !shown(doc))
+                    return finish(404, { error: "not_found" });
+                finish(200, { ...r.value, building: r.building });
+            }, () => failed("unavailable"));
+            return true;
+        }
+        const parsed = parseSearchQuery(url, ctx);
+        if ("error" in parsed) {
+            json(res, 400, { error: parsed.error });
+            return true;
+        }
+        if (parsed.mine) {
+            const person = webPersonOf(req, url, ctx);
+            if (!person) {
+                json(res, 401, { error: WEB_TOKEN_INVALID_MESSAGE });
+                return true;
+            }
+            parsed.filters.mine = [person.voterKey];
+        }
+        const v = visibility();
+        if ("hidden" in v)
+            parsed.filters.hidden = v.hidden;
+        else
+            parsed.filters.xmsgAmong = v.among;
+        void index.query(parsed.filters).then(r => {
+            if (!r.ok)
+                return failed(r.reason);
+            // A chat row still in the history opens in place (#m=); one that has left it opens as the index's copy.
+            const history = ctx.webChatHistory;
+            // The visibility as it is now (#2295 review): a name hidden while the query ran is left out too.
+            const now = visibility();
+            const hits = r.value.hits.filter(h => xmsgShown(h, now)).map(h => h.source !== "chat" ? h
+                : { ...h, live: !!history?.find(h.instance, String(h.ref.boot ?? ""), Number(h.ref.id)) });
+            finish(200, { hits, limited: r.value.limited, building: r.building });
+        }, () => failed("unavailable"));
+        return true;
+    }
     // #2122: the usage report. Signed-in sessions by default (guests never: not in GUEST_ROUTES); hidden with the rest of
     // usage by web.usage_panel: false; over the public link only when web.usage_report_on_public_link is true. Answered
     // from the ledgers and rollups as they are; a catch-up runs behind. The page's CSV is built from this same answer.