@mono-agent/web 0.20.11 → 0.21.0

package/dist/server.js

@@ -4,15 +4,17 @@ import { chmod, open, readFile, rename, unlink } from "node:fs/promises";
 import { createServer } from "node:http";
 import { isIP } from "node:net";
 import { hostname as systemHostname } from "node:os";
-import { dirname, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { fileURLToPath } from "node:url";
-import { AGENT_LIVE_INPUT_MAX_CHARACTERS, closeServerBounded, hostForUrl, listen, normalizeHostForBind, } from "@mono-agent/agent-contracts";
+import { constants as zlibConstants } from "node:zlib";
+import { AGENT_LIVE_INPUT_MAX_CHARACTERS, closeServerBounded, hostForUrl, listen, MAX_PROVIDER_AUTH_BODY_BYTES, normalizeHostForBind, parseProviderAuthSessionInput, parseProviderAuthSessionStartInput, parseProviderAuthCheckStartInput, } from "@mono-agent/agent-contracts";
+import compression from "compression";
 import express, {} from "express";
-import { DEFAULT_WEB_THEME, WEB_API_VERSION, WEB_MAX_TURN_TEXT_CHARACTERS, WEB_THEMES, } from "./contracts.js";
+import { DEFAULT_WEB_THEME, WEB_API_VERSION, WEB_CONSOLE_NAME_MAX_CHARACTERS, WEB_MAX_TURN_TEXT_CHARACTERS, WEB_THEMES, } from "./contracts.js";
 import { errorMessage, WebConsoleError } from "./errors.js";
-import { WEB_THREAD_SEARCH_MAX } from "./store.js";
+import { WEB_MESSAGE_PAGE_DEFAULT, WEB_MESSAGE_PAGE_MAX, WEB_THREAD_PAGE_DEFAULT, WEB_THREAD_PAGE_MAX, WEB_THREAD_SEARCH_MAX, } from "./store.js";
 import { MCP_APP_PROXY_CONTENT_SECURITY_POLICY, MCP_APP_PROXY_DOCUMENT, MCP_APP_PROXY_PATH, } from "./mcp-app-proxy.js";
 import { startWebNotificationIngress, } from "./notification-ingress.js";
 import { WebService } from "./service.js";
@@ -20,20 +22,49 @@ export const DEFAULT_WEB_HOST = "0.0.0.0";
 export const DEFAULT_WEB_PORT = 5050;
 const HEARTBEAT_INTERVAL_MS = 15_000;
 const MAX_SSE_CLIENTS = 64;
+/**
+ * How often one connection may be told that one conversation's message moved,
+ * when it is not subscribed to that conversation's content.
+ *
+ * A hint costs its reader a re-read, and a streaming turn produces one write
+ * every 50 ms. A console that is not looking at the conversation has no reason
+ * to follow it at that rate -- it needs the sidebar row to be right, which the
+ * conversation events already carry.
+ */
+const DELTA_HINT_INTERVAL_MS = 1_000;
+/** Bound on `?thread=`, matching the other bounded query strings. */
+const MAX_SUBSCRIPTION_LENGTH = 512;
+/**
+ * How many conversations one connection remembers having hinted about.
+ *
+ * A hard bound, evicting the least recently hinted: a burst wider than this
+ * inside one second would otherwise grow the map faster than the window can
+ * retire it. Evicting an entry that is still inside its window costs one extra
+ * hint for that conversation; an unbounded map on a server that runs for weeks
+ * costs the server.
+ */
+const MAX_THROTTLED_CONVERSATIONS = 256;
 const MAX_MCP_APP_BRIDGE_REQUEST_BYTES = 64 * 1024;
-const WEB_THEME_CHROME = {
-    evergreen: { light: "#eeefeb", dark: "#0f1110" },
-    ocean: { light: "#edf1f4", dark: "#0d1115" },
-    plum: { light: "#f2eef3", dark: "#120f14" },
-    terracotta: { light: "#f4efec", dark: "#130f0d" },
+/**
+ * Content-addressed build output and write-once upload bytes never change under
+ * their URL, so the browser may hold them for a year and skip the request.
+ */
+const IMMUTABLE_MAX_AGE_SECONDS = 365 * 24 * 60 * 60;
+const WEB_THEME_MANIFEST_COLORS = {
+    evergreen: { themeColor: "#191c1a", backgroundColor: "#0f1110" },
+    ocean: { themeColor: "#191c1a", backgroundColor: "#0d1115" },
+    plum: { themeColor: "#191c1a", backgroundColor: "#120f14" },
+    terracotta: { themeColor: "#191c1a", backgroundColor: "#130f0d" },
 };
 export async function startWebServer(options = {}) {
     const host = normalizeHostForBind(options.host ?? DEFAULT_WEB_HOST);
     const port = normalizePort(options.port ?? DEFAULT_WEB_PORT);
     const staticDir = options.staticDir ?? defaultStaticDir();
     const theme = resolveWebTheme(options.theme);
+    const hostName = systemHostname().trim() || "localhost";
     const consoleIdentity = {
-        hostName: systemHostname().trim() || "localhost",
+        hostName,
+        displayName: resolveWebConsoleName(options.name) ?? hostName,
         theme,
     };
     const webManifest = await loadWebManifest(staticDir, consoleIdentity);
@@ -52,11 +83,30 @@ export async function startWebServer(options = {}) {
     let notificationIngress;
     let stopPromise;
     app.disable("x-powered-by");
+    // Mounted first so every response body, error JSON included, is negotiated.
+    // Brotli quality 4 keeps a phone-sized payload under a few milliseconds of
+    // CPU; the default filter already declines anything the response marked
+    // `no-transform` (SSE, attachment bytes) or that is not compressible.
+    app.use(compression({
+        threshold: 1024,
+        level: 6,
+        brotli: { params: { [zlibConstants.BROTLI_PARAM_QUALITY]: 4 } },
+    }));
     app.use(securityHeaders);
     app.use(validateLocalRequest(host, allowedHosts));
+    // Console state is private to this operator but not secret from their own
+    // browser: `no-cache` still forces revalidation on every read, and lets
+    // Express answer an unchanged payload with a 304 instead of resending it.
     app.use("/api", (_req, res, next) => {
-        res.setHeader("Cache-Control", "no-store");
-        res.setHeader("Pragma", "no-cache");
+        res.setHeader("Cache-Control", "private, no-cache");
+        next();
+    });
+    app.use("/api/v1/threads/:id/submissions", (_req, res, next) => {
+        res.setHeader("Cache-Control", "private, no-store, max-age=0");
+        next();
+    });
+    app.use("/api/v1/agents/:id/cron/jobs/:jobId/runs/:runId/reply-threads", (_req, res, next) => {
+        res.setHeader("Cache-Control", "private, no-store, max-age=0");
         next();
     });
     app.use("/api/v1", express.json({ limit: "256kb", strict: true }));
@@ -67,10 +117,26 @@ export async function startWebServer(options = {}) {
             push: service.webPushDegraded() ? "degraded" : "ok",
         });
     });
-    app.get("/api/v1/bootstrap", (_req, res, next) => {
-        void service.bootstrap()
-            .then((bootstrap) => res.status(200).json({ ...bootstrap, console: consoleIdentity }))
-            .catch(next);
+    app.get("/api/v1/bootstrap", (req, res, next) => {
+        try {
+            // One bucket, not every agent's conversations. An unknown or absent
+            // `sourceId` falls back inside the service rather than failing: the
+            // first request a fresh console makes has no selection to name yet.
+            // An empty `sourceId` is a console that has not resolved an agent yet,
+            // which is the same thing as omitting it -- not a malformed request.
+            const requested = req.query.sourceId === "" ? undefined : req.query.sourceId;
+            const sourceId = optionalQueryString(requested, 512);
+            void service.bootstrap({
+                ...(sourceId === undefined ? {} : { sourceId }),
+                archived: optionalArchivedQuery(req.query.archived) ?? false,
+                limit: boundedQueryLimit(req.query.limit, WEB_THREAD_PAGE_MAX, WEB_THREAD_PAGE_DEFAULT),
+            })
+                .then((bootstrap) => res.status(200).json({ ...bootstrap, console: consoleIdentity }))
+                .catch(next);
+        }
+        catch (error) {
+            next(error);
+        }
     });
     app.get(MCP_APP_PROXY_PATH, (_req, res) => {
         setMcpAppProxyHeaders(res);
@@ -91,6 +157,115 @@ export async function startWebServer(options = {}) {
             next(error);
         }
     });
+    app.put("/api/v1/agents/:id/run-defaults", (req, res, next) => {
+        try {
+            const input = parsePutAgentRunSettings(req.body);
+            res.status(200).json({ agent: service.setAgentRunDefaults(pathParam(req.params.id), input) });
+        }
+        catch (error) {
+            next(error);
+        }
+    });
+    app.delete("/api/v1/agents/:id/run-defaults", (req, res, next) => {
+        try {
+            res.status(200).json({ agent: service.clearAgentRunDefaults(pathParam(req.params.id)) });
+        }
+        catch (error) {
+            next(error);
+        }
+    });
+    const sendProviderAuth = (res, status, body) => {
+        res.setHeader("Cache-Control", "private, no-store, max-age=0");
+        if (status === 204)
+            res.status(status).end();
+        else
+            res.status(status).json(body);
+    };
+    app.use("/api/v1/agents/:id/provider-auth", (_req, res, next) => {
+        res.setHeader("Cache-Control", "private, no-store, max-age=0");
+        next();
+    });
+    app.get("/api/v1/agents/:id/provider-auth", (req, res, next) => {
+        try {
+            exactRequestOrigin(req);
+            void trackOperation(service.providerAuthStatus(pathParam(req.params.id)), activeOperations)
+                .then((snapshot) => sendProviderAuth(res, 200, snapshot)).catch(next);
+        }
+        catch (error) {
+            next(error);
+        }
+    });
+    app.post("/api/v1/agents/:id/provider-auth/sessions", (req, res, next) => {
+        try {
+            exactRequestOrigin(req);
+            assertProviderAuthBody(req.body);
+            const input = parseProviderAuthSessionStartInput(req.body);
+            void trackOperation(service.startProviderAuth(pathParam(req.params.id), input), activeOperations)
+                .then((snapshot) => sendProviderAuth(res, 201, snapshot)).catch(next);
+        }
+        catch (error) {
+            next(error);
+        }
+    });
+    app.get("/api/v1/agents/:id/provider-auth/sessions/:sessionId", (req, res, next) => {
+        try {
+            exactRequestOrigin(req);
+            void trackOperation(service.providerAuthSession(pathParam(req.params.id), pathParam(req.params.sessionId)), activeOperations).then((snapshot) => sendProviderAuth(res, 200, snapshot)).catch(next);
+        }
+        catch (error) {
+            next(error);
+        }
+    });
+    app.post("/api/v1/agents/:id/provider-auth/sessions/:sessionId/input", (req, res, next) => {
+        try {
+            exactRequestOrigin(req);
+            assertProviderAuthBody(req.body);
+            const input = parseProviderAuthSessionInput(req.body);
+            void trackOperation(service.submitProviderAuth(pathParam(req.params.id), pathParam(req.params.sessionId), input), activeOperations).then((snapshot) => sendProviderAuth(res, 200, snapshot)).catch(next);
+        }
+        catch (error) {
+            next(error);
+        }
+    });
+    app.delete("/api/v1/agents/:id/provider-auth/sessions/:sessionId", (req, res, next) => {
+        try {
+            exactRequestOrigin(req);
+            void trackOperation(service.cancelProviderAuth(pathParam(req.params.id), pathParam(req.params.sessionId)), activeOperations).then(() => sendProviderAuth(res, 204)).catch(next);
+        }
+        catch (error) {
+            next(error);
+        }
+    });
+    app.post("/api/v1/agents/:id/provider-auth/checks", (req, res, next) => {
+        try {
+            exactRequestOrigin(req);
+            assertProviderAuthBody(req.body);
+            const input = parseProviderAuthCheckStartInput(req.body);
+            void trackOperation(service.startProviderAuthCheck(pathParam(req.params.id), input), activeOperations)
+                .then((snapshot) => sendProviderAuth(res, 201, snapshot)).catch(next);
+        }
+        catch (error) {
+            next(error);
+        }
+    });
+    app.get("/api/v1/agents/:id/provider-auth/checks/:checkId", (req, res, next) => {
+        try {
+            exactRequestOrigin(req);
+            void trackOperation(service.providerAuthCheck(pathParam(req.params.id), pathParam(req.params.checkId)), activeOperations).then((snapshot) => sendProviderAuth(res, 200, snapshot)).catch(next);
+        }
+        catch (error) {
+            next(error);
+        }
+    });
+    app.delete("/api/v1/agents/:id/provider-auth/checks/:checkId", (req, res, next) => {
+        try {
+            exactRequestOrigin(req);
+            void trackOperation(service.cancelProviderAuthCheck(pathParam(req.params.id), pathParam(req.params.checkId)), activeOperations).then(() => sendProviderAuth(res, 204)).catch(next);
+        }
+        catch (error) {
+            next(error);
+        }
+    });
     app.get("/api/v1/agents/:id/skills", (req, res, next) => {
         try {
             res.status(200).json(service.agentSkills(pathParam(req.params.id)));
@@ -119,9 +294,49 @@ export async function startWebServer(options = {}) {
             next(error);
         }
     });
+    app.get("/api/v1/agents/:id/models", (req, res, next) => {
+        try {
+            // The operator clamps to the same 200-model page ceiling; mirror it
+            // server-side rather than trusting the client's requested size.
+            const limit = boundedQueryLimit(req.query.limit, 200, 50);
+            const provider = optionalSearchQuery(req.query.provider, 256);
+            const q = optionalSearchQuery(req.query.q, 512);
+            // The agent's `/v1/models` contract treats the two modes as mutually
+            // exclusive: a supplier services `provider` and ignores the query, so a
+            // request carrying both comes back looking like an answered search. The
+            // agent rejects it, but the operator client re-reports any agent 4xx as
+            // a 502 `agent_http_error` -- which blames the agent for the caller's
+            // mistake. Keep this one local and legible.
+            if (provider.length > 0 && q.length > 0) {
+                throw new WebConsoleError("invalid_page", "provider and q are mutually exclusive for the model catalog.", 400);
+            }
+            const cursor = optionalQueryString(req.query.cursor, 4_096);
+            void trackOperation(service.agentModels(pathParam(req.params.id), {
+                limit,
+                ...(provider.length === 0 ? {} : { provider }),
+                ...(q.length === 0 ? {} : { q }),
+                ...(cursor === undefined ? {} : { cursor }),
+            }), activeOperations).then((page) => res.status(200).json(page)).catch(next);
+        }
+        catch (error) {
+            next(error);
+        }
+    });
     app.get("/api/v1/agents/:id/cron/jobs/:jobId/runs/:runId", (req, res, next) => {
         void trackOperation(service.cronRun(pathParam(req.params.id), pathParam(req.params.jobId), pathParam(req.params.runId)), activeOperations).then((message) => res.status(200).json({ message })).catch(next);
     });
+    app.post("/api/v1/agents/:id/cron/jobs/:jobId/runs/:runId/reply-threads", (req, res, next) => {
+        try {
+            exactRequestOrigin(req);
+            const input = parseCronReply(req.body);
+            void trackOperation(service.createCronReplyThread(pathParam(req.params.id), pathParam(req.params.jobId), pathParam(req.params.runId), input), activeOperations).then((receipt) => {
+                res.status(receipt.duplicate ? 200 : 201).json(receipt);
+            }).catch(next);
+        }
+        catch (error) {
+            next(error);
+        }
+    });
     app.post("/api/v1/agents/:id/cron/jobs/:jobId/run", (req, res, next) => {
         try {
             exactRequestOrigin(req);
@@ -149,7 +364,10 @@ export async function startWebServer(options = {}) {
     app.post("/api/v1/threads", (req, res, next) => {
         try {
             const input = parseCreateThread(req.body);
-            res.status(201).json({ thread: service.createThread(input.sourceId) });
+            res.status(201).json({ thread: service.createThread(input.sourceId, {
+                    ...(input.model === undefined ? {} : { model: input.model }),
+                    ...(input.effort === undefined ? {} : { effort: input.effort }),
+                }) });
         }
         catch (error) {
             next(error);
@@ -158,16 +376,17 @@ export async function startWebServer(options = {}) {
     app.get("/api/v1/threads", (req, res, next) => {
         try {
             const sourceId = requiredQueryString(req.query.sourceId, "sourceId", 512);
-            const archived = req.query.archived === "true"
-                ? true
-                : req.query.archived === "false"
-                    ? false
-                    : (() => { throw new WebConsoleError("invalid_page", "archived must be true or false.", 400); })();
+            const archived = optionalArchivedQuery(req.query.archived);
+            if (archived === undefined) {
+                throw new WebConsoleError("invalid_page", "archived must be true or false.", 400);
+            }
             const before = optionalQueryString(req.query.before, 4_096);
             res.status(200).json(service.threadsPage({
                 sourceId,
                 archived,
-                limit: boundedQueryLimit(req.query.limit, 200, 200),
+                // A sidebar shows a handful of rows and pages from there. This used to
+                // answer with the whole per-bucket cap by default.
+                limit: boundedQueryLimit(req.query.limit, WEB_THREAD_PAGE_MAX, WEB_THREAD_PAGE_DEFAULT),
                 ...(before === undefined ? {} : { before }),
             }));
         }
@@ -190,9 +409,35 @@ export async function startWebServer(options = {}) {
             next(error);
         }
     });
+    // Registered above `/threads/:id` so the conversation reads and the read that
+    // repairs one of their truncated tool calls stay together.
+    app.get("/api/v1/threads/:threadId/messages/:messageId/tool-calls/:toolCallId", (req, res, next) => {
+        try {
+            res.status(200).json({
+                part: service.toolCallPart(pathParam(req.params.threadId), pathParam(req.params.messageId), pathParam(req.params.toolCallId)),
+            });
+        }
+        catch (error) {
+            next(error);
+        }
+    });
+    // Registered above `/threads/:id` and above the message page for the same
+    // reason the tool-call read is: this is how a console whose delta stream
+    // skipped a version repairs ONE message instead of re-reading the whole
+    // conversation around it.
+    app.get("/api/v1/threads/:threadId/messages/:messageId", (req, res, next) => {
+        try {
+            res.status(200).json({
+                message: service.message(pathParam(req.params.threadId), pathParam(req.params.messageId), fullTranscriptQuery(req.query.full)),
+            });
+        }
+        catch (error) {
+            next(error);
+        }
+    });
     app.get("/api/v1/threads/:id", (req, res, next) => {
         try {
-            res.status(200).json(service.thread(pathParam(req.params.id)));
+            res.status(200).json(service.thread(pathParam(req.params.id), fullTranscriptQuery(req.query.full)));
         }
         catch (error) {
             next(error);
@@ -202,8 +447,11 @@ export async function startWebServer(options = {}) {
         try {
             const before = optionalQueryString(req.query.before, 4_096);
             res.status(200).json(service.messagePage(pathParam(req.params.id), {
-                limit: boundedQueryLimit(req.query.limit, 100, 100),
+                // A screenful, not the ceiling: the console renders the tail and pages
+                // backwards from the cursor.
+                limit: boundedQueryLimit(req.query.limit, WEB_MESSAGE_PAGE_MAX, WEB_MESSAGE_PAGE_DEFAULT),
                 ...(before === undefined ? {} : { before }),
+                ...fullTranscriptQuery(req.query.full),
             }));
         }
         catch (error) {
@@ -227,10 +475,10 @@ export async function startWebServer(options = {}) {
             if (!res.writableEnded)
                 controller.abort(new Error("Reply attachment client disconnected."));
         });
-        void trackOperation(service.replyAttachment(pathParam(req.params.threadId), pathParam(req.params.messageId), pathParam(req.params.partId), access.expires, access.token, controller.signal).then(async ({ part, response }) => {
+        void trackOperation(service.replyAttachment(pathParam(req.params.threadId), pathParam(req.params.messageId), pathParam(req.params.partId), access.expires, access.token, controller.signal).then(async ({ part, response, remainingSeconds }) => {
             if (response.body === null)
                 throw new WebConsoleError("reply_attachment_unavailable", "Attachment stream is unavailable.", 502);
-            setReplyDownloadHeaders(res, part);
+            setReplyDownloadHeaders(res, part, remainingSeconds);
             await pipeline(Readable.fromWeb(response.body), res);
         }), activeOperations).catch((error) => {
             if (res.headersSent) {
@@ -304,9 +552,15 @@ export async function startWebServer(options = {}) {
         }
     });
     app.delete("/api/v1/threads/:id", (req, res, next) => {
-        void trackOperation(service.deleteThread(pathParam(req.params.id)), activeOperations)
-            .then(() => res.status(204).end())
-            .catch(next);
+        try {
+            const emptyOnly = optionalEmptyOnlyQuery(req.query.emptyOnly);
+            void trackOperation(service.deleteThread(pathParam(req.params.id), { emptyOnly }), activeOperations)
+                .then(() => res.status(204).end())
+                .catch(next);
+        }
+        catch (error) {
+            next(error);
+        }
     });
     app.post("/api/v1/threads/:id/turns", (req, res, next) => {
         let input;
@@ -323,6 +577,25 @@ export async function startWebServer(options = {}) {
             .then((started) => res.status(202).json(started))
             .catch(next);
     });
+    app.post("/api/v1/threads/:id/submissions", (req, res, next) => {
+        try {
+            const input = parseSubmission(req.body);
+            const receipt = service.submit(pathParam(req.params.id), input);
+            res.status(receipt.outcome === "rejected" ? 409 : 202).json(receipt);
+        }
+        catch (error) {
+            next(error);
+        }
+    });
+    app.get("/api/v1/threads/:id/submissions/:submissionId", (req, res, next) => {
+        try {
+            const receipt = service.submission(pathParam(req.params.id), parseSubmissionId(pathParam(req.params.submissionId)));
+            res.status(200).json(receipt);
+        }
+        catch (error) {
+            next(error);
+        }
+    });
     app.post("/api/v1/threads/:id/live-input", (req, res, next) => {
         try {
             const input = parseLiveInput(req.body);
@@ -430,11 +703,40 @@ export async function startWebServer(options = {}) {
     app.get("/api/v1/uploads/:id/content", (req, res, next) => {
         void trackOperation(handleDownloadContent(pathParam(req.params.id), res, service), activeOperations).catch(next);
     });
-    app.get("/api/v1/events", (_req, res) => {
+    /**
+     * The console's live channel. {@link createWebEventDispatch} decides what each
+     * connection is served; this owns the socket, the capacity cap and the
+     * heartbeat.
+     */
+    app.get("/api/v1/events", (req, res, next) => {
+        let named;
+        try {
+            named = optionalThreadSubscription(req.query.thread);
+        }
+        catch (error) {
+            next(error);
+            return;
+        }
         if (activeStreams.size >= MAX_SSE_CLIENTS) {
             res.status(503).json({ error: { code: "sse_capacity", message: "Too many event streams are connected." } });
             return;
         }
+        let subscribed;
+        try {
+            // The CANONICAL id, because that is what every event carries. A console
+            // restores a selection it stored before a cron-channel adoption merged
+            // that conversation away, or opens a push link minted against the old id;
+            // matched by string equality, both subscribed to nothing and were served
+            // throttled hints for the conversation they had open.
+            //
+            // AFTER the capacity check: this reads the database, and a console the
+            // server is about to refuse must not be able to make it work.
+            subscribed = named === undefined ? undefined : service.resolveThreadId(named);
+        }
+        catch (error) {
+            next(error);
+            return;
+        }
         let closed = false;
         res.status(200);
         res.setHeader("Content-Type", "text/event-stream");
@@ -451,18 +753,23 @@ export async function startWebServer(options = {}) {
             activeStreams.delete(closeStream);
             res.end();
         };
-        const send = (event) => {
-            if (closed || res.writableEnded)
-                return false;
-            const writable = res.write(formatSse(event));
-            if (!writable) {
+        const send = createWebEventDispatch({
+            ...(subscribed === undefined ? {} : { subscribed }),
+            write: (event) => {
+                if (closed || res.writableEnded)
+                    return false;
+                if (res.write(formatSse(event)))
+                    return true;
                 // Events are state-invalidation hints, not an unbounded replay log. A
                 // client that cannot drain one frame must reconnect and bootstrap.
                 closeStream();
                 return false;
-            }
-            return true;
-        };
+            },
+            close: closeStream,
+            onFailure: (error) => {
+                logger?.error?.("Web console event stream failed.", { error: errorMessage(error) });
+            },
+        });
         const unsubscribe = service.subscribe(send);
         const heartbeat = setInterval(() => {
             if (!res.write(`: heartbeat ${Date.now()}\n\n`))
@@ -476,12 +783,28 @@ export async function startWebServer(options = {}) {
     app.use("/api", (_req, res) => {
         res.status(404).json({ error: { code: "not_found", message: "Not found." } });
     });
-    app.use(express.static(staticDir, { fallthrough: true, index: false, redirect: false }));
+    // Vite fingerprints everything under assets/, so those URLs are immutable and
+    // must be mounted ahead of the revalidating root. The root then covers the
+    // service workers, icons, and the shell, which keep their names across builds
+    // and so have to be revalidated (cheaply, against their ETag) every load.
+    app.use("/assets", express.static(join(staticDir, "assets"), {
+        fallthrough: true,
+        index: false,
+        redirect: false,
+        immutable: true,
+        maxAge: IMMUTABLE_MAX_AGE_SECONDS * 1000,
+    }));
+    app.use(express.static(staticDir, {
+        fallthrough: true,
+        index: false,
+        redirect: false,
+        setHeaders: (res) => res.setHeader("Cache-Control", "no-cache"),
+    }));
     app.get("/{*splat}", (_req, res, next) => {
         // Keep the managed runtime's hidden ~/.mono-agent parent out of the
         // request-relative path. Express otherwise applies its dotfile policy to
         // the absolute path and rejects an existing index.html as Not Found.
-        res.sendFile("index.html", { root: staticDir }, (error) => {
+        res.sendFile("index.html", { root: staticDir, headers: { "Cache-Control": "no-cache" } }, (error) => {
             if (error !== undefined && error !== null)
                 next(error);
         });
@@ -497,6 +820,12 @@ export async function startWebServer(options = {}) {
             && (error.status === 413 || error.type === "entity.too.large");
         const status = known ? error.status : tooLarge ? 413 : syntax ? 400 : 500;
         const code = known ? error.code : tooLarge ? "request_too_large" : syntax ? "invalid_json" : "internal_error";
+        const retryAfterSeconds = known && typeof error.details?.retryAfterSeconds === "number"
+            ? error.details.retryAfterSeconds
+            : undefined;
+        if (status === 429 && Number.isSafeInteger(retryAfterSeconds) && retryAfterSeconds > 0) {
+            res.setHeader("Retry-After", String(retryAfterSeconds));
+        }
         if (status >= 500)
             logger?.error?.("Web console request failed.", { error: errorMessage(error) });
         res.status(status).json({
@@ -555,6 +884,28 @@ export async function startWebServer(options = {}) {
         throw error;
     }
 }
+/**
+ * Normalize the operator-chosen console label. Control characters are rejected rather
+ * than stripped so a typo cannot silently install under a different name than requested.
+ */
+function resolveWebConsoleName(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string") {
+        throw new WebConsoleError("invalid_console_name", "Web console name must be a string.", 400);
+    }
+    const name = value.trim();
+    if (name.length === 0) {
+        throw new WebConsoleError("invalid_console_name", "Web console name must not be empty.", 400);
+    }
+    if (/[\u0000-\u001f\u007f-\u009f\u2028-\u202e]/u.test(name)) {
+        throw new WebConsoleError("invalid_console_name", "Web console name must not contain control characters, line separators, or bidirectional overrides.", 400);
+    }
+    if ([...name].length > WEB_CONSOLE_NAME_MAX_CHARACTERS) {
+        throw new WebConsoleError("invalid_console_name", `Web console name must be at most ${String(WEB_CONSOLE_NAME_MAX_CHARACTERS)} characters.`, 400);
+    }
+    return name;
+}
 function resolveWebTheme(value) {
     if (value === undefined)
         return DEFAULT_WEB_THEME;
@@ -584,13 +935,13 @@ async function loadWebManifest(staticDir, identity) {
     if (template === null || typeof template !== "object" || Array.isArray(template)) {
         throw new WebConsoleError("invalid_static_manifest", "The web console manifest must be a JSON object.", 500);
     }
-    const chrome = WEB_THEME_CHROME[identity.theme];
+    const colors = WEB_THEME_MANIFEST_COLORS[identity.theme];
     return {
         ...template,
-        name: `${identity.hostName} · mono-agent Console`,
-        short_name: identity.hostName,
-        theme_color: chrome.dark,
-        background_color: chrome.dark,
+        name: `${identity.displayName} · mono-agent Console`,
+        short_name: identity.displayName,
+        theme_color: colors.themeColor,
+        background_color: colors.backgroundColor,
     };
 }
 function trackOperation(operation, active) {
@@ -690,6 +1041,10 @@ async function handleDownloadContent(id, res, service) {
     res.status(200);
     res.setHeader("Content-Type", image ? attachment.contentType : "application/octet-stream");
     res.setHeader("Content-Length", String(info.size));
+    // An upload id is a fresh UUID whose bytes are written exactly once, so this
+    // URL can never change meaning. `no-transform` keeps the declared length
+    // honest for the client that streams these bytes back into a Blob.
+    res.setHeader("Cache-Control", `private, max-age=${IMMUTABLE_MAX_AGE_SECONDS}, immutable, no-transform`);
     res.setHeader("X-Content-Type-Options", "nosniff");
     res.setHeader("Content-Security-Policy", "default-src 'none'; sandbox");
     res.setHeader("Content-Disposition", contentDisposition(attachment.name, image ? "inline" : "attachment"));
@@ -707,7 +1062,9 @@ function replyAccessQuery(req) {
     }
     return { expires, token };
 }
-function setReplyDownloadHeaders(res, part) {
+function setReplyDownloadHeaders(res, part, 
+/** Seconds this response's own capability is still good for. */
+maxAgeSeconds) {
     const risky = /^(?:text\/(?:html|javascript|xml)|application\/(?:javascript|xhtml\+xml|xml)|image\/svg\+xml)$/iu
         .test(part.mediaType);
     res.status(200);
@@ -717,7 +1074,16 @@ function setReplyDownloadHeaders(res, part) {
     res.setHeader("Content-Length", String(part.sizeBytes));
     res.setHeader("Accept-Ranges", "none");
     res.setHeader("Content-Disposition", contentDisposition(part.name, "attachment"));
-    res.setHeader("Cache-Control", "private, no-store, max-age=0");
+    // The client refuses a part whose Content-Length disagrees with the declared
+    // size, so this response must reach it byte-for-byte -- hence `no-transform`.
+    //
+    // Cacheable for exactly as long as the signed key in the URL is: the mint
+    // quantises its expiry to a five-minute bucket, so the same picture asked for
+    // twice inside one bucket is the same URL and the browser answers the second
+    // read itself. `private`, because the URL is a capability and no shared cache
+    // may keep it; never past the key, because the response is only servable while
+    // the key is.
+    res.setHeader("Cache-Control", `private, max-age=${String(maxAgeSeconds)}, no-transform`);
     res.setHeader("X-Content-Type-Options", "nosniff");
     res.setHeader("Content-Security-Policy", "sandbox; default-src 'none'; base-uri 'none'; form-action 'none'");
     res.setHeader("Cross-Origin-Resource-Policy", "same-origin");
@@ -845,7 +1211,31 @@ function securityHeaders(_req, res, next) {
 }
 function parseCreateThread(value) {
     const body = requireRecord(value);
-    return { sourceId: requireString(body.sourceId, "sourceId", 256) };
+    const model = optionalNullableString(body.model, "model", 120);
+    const effort = optionalNullableString(body.effort, "effort", 120);
+    return {
+        sourceId: requireString(body.sourceId, "sourceId", 256),
+        ...(model === undefined ? {} : { model }),
+        ...(effort === undefined ? {} : { effort }),
+    };
+}
+function parsePutAgentRunSettings(value) {
+    const body = requireRecord(value);
+    if (!("model" in body) || !("effort" in body)) {
+        throw invalidBody("model and effort are required and must be strings or null.");
+    }
+    const unknown = Object.keys(body).filter((key) => key !== "model" && key !== "effort");
+    if (unknown.length > 0)
+        throw invalidBody(`Unknown run-defaults field: ${unknown[0]}.`);
+    const model = optionalNullableString(body.model, "model", 120);
+    const effort = optionalNullableString(body.effort, "effort", 120);
+    if (model === undefined || effort === undefined) {
+        throw invalidBody("model and effort are required and must be strings or null.");
+    }
+    if (model === null && effort === null) {
+        throw invalidBody("Choose a model or effort override, or use Revert to config.");
+    }
+    return { model, effort };
 }
 function parsePatchAgent(value) {
     const body = requireRecord(value);
@@ -856,12 +1246,25 @@ function parsePatchAgent(value) {
 function parsePatchThread(value) {
     const body = requireRecord(value);
     const title = optionalString(body.title, "title", 120);
+    const model = optionalNullableString(body.model, "model", 120);
+    const effort = optionalNullableString(body.effort, "effort", 120);
     const archived = body.archived;
     if (archived !== undefined && typeof archived !== "boolean")
         throw invalidBody("archived must be boolean.");
-    if (title === undefined && archived === undefined)
-        throw invalidBody("Provide title or archived.");
-    return { ...(title === undefined ? {} : { title }), ...(archived === undefined ? {} : { archived }) };
+    const ifRunConfigUnset = body.ifRunConfigUnset;
+    if (ifRunConfigUnset !== undefined && typeof ifRunConfigUnset !== "boolean") {
+        throw invalidBody("ifRunConfigUnset must be boolean.");
+    }
+    if (title === undefined && archived === undefined && model === undefined && effort === undefined) {
+        throw invalidBody("Provide title, archived, model, or effort.");
+    }
+    return {
+        ...(title === undefined ? {} : { title }),
+        ...(archived === undefined ? {} : { archived }),
+        ...(model === undefined ? {} : { model }),
+        ...(effort === undefined ? {} : { effort }),
+        ...(ifRunConfigUnset === undefined ? {} : { ifRunConfigUnset }),
+    };
 }
 function parseTurn(value) {
     const body = requireRecord(value);
@@ -889,6 +1292,29 @@ function parseTurn(value) {
         ...(effort === undefined ? {} : { effort }),
     };
 }
+function parseSubmission(value) {
+    const body = requireRecord(value);
+    const submissionId = parseSubmissionId(body.submissionId);
+    return { ...parseTurn(body), submissionId };
+}
+function parseSubmissionId(value) {
+    const submissionId = requireString(value, "submissionId", 36);
+    if (!/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu.test(submissionId)) {
+        throw invalidBody("submissionId must be a canonical UUID.");
+    }
+    return submissionId.toLowerCase();
+}
+function parseCronReply(value) {
+    const body = requireRecord(value);
+    if (Object.keys(body).sort().join("\0") !== ["operationId", "snapshotKind"].join("\0")) {
+        throw invalidBody("Cron Reply requires only operationId and snapshotKind.");
+    }
+    const operationId = parseSubmissionId(body.operationId);
+    if (body.snapshotKind !== "summary" && body.snapshotKind !== "detail") {
+        throw invalidBody("snapshotKind must be summary or detail.");
+    }
+    return { operationId, snapshotKind: body.snapshotKind };
+}
 function parseLiveInput(value) {
     const body = requireRecord(value);
     return {
@@ -977,6 +1403,142 @@ function requireRecord(value) {
         throw invalidBody("JSON body must be an object.");
     return value;
 }
+function assertProviderAuthBody(value) {
+    let bytes;
+    try {
+        bytes = Buffer.byteLength(JSON.stringify(value) ?? "null", "utf8");
+    }
+    catch {
+        throw invalidBody("Provider authentication body must be JSON.");
+    }
+    if (bytes > MAX_PROVIDER_AUTH_BODY_BYTES) {
+        throw new WebConsoleError("provider_auth_too_large", "Provider authentication body is too large.", 413);
+    }
+}
+/**
+ * One connection's view of the event stream: which frames it is served, and in
+ * what form.
+ *
+ * A console names the conversation it is looking at with `?thread=`. It is
+ * served EVERYTHING about that conversation unthrottled -- `message.delta`
+ * frames carrying what each write changed, and the `message.changed` hints the
+ * delta path emits when it declines (a delta bigger than the message, a
+ * reconciliation that describes nothing), because both are things it must act
+ * on. Anything about any OTHER conversation is reduced to a
+ * `message.changed { messageId, updatedAt }` and rate-limited to one per
+ * conversation per {@link DELTA_HINT_INTERVAL_MS}, dropped rather than queued:
+ * a console is not rendering it.
+ *
+ * A console that named NO conversation is not telling this stream which
+ * conversation it is looking at, so it keeps every reconciliation hint and is
+ * rate-limited only on what the delta path produces -- downgraded deltas and
+ * the declines above -- which is the write-rate traffic the limit exists for. A
+ * turn's `thread.changed` still follows every finish unthrottled, so a dropped
+ * frame never leaves a settled conversation stale.
+ *
+ * Every other event type passes through untouched. `Last-Event-ID` is ignored
+ * and nothing is replayed: this is state invalidation, not a log. A
+ * reconnecting console bootstraps, and `ready` means resync the conversation it
+ * has open.
+ *
+ * Lives outside the route because neither of the two things that matter is
+ * observable through an HTTP fixture: the rate limit is a clock decision, and a
+ * frame this connection cannot serialize or write must CLOSE it rather than
+ * leave a socket that reads live and receives nothing.
+ */
+export function createWebEventDispatch(options) {
+    const { subscribed, write, close, onFailure } = options;
+    const now = options.now ?? (() => Date.now());
+    // Per connection, and cleared with it: what one console has already been told
+    // about is no reason to keep another quiet.
+    const hintedAt = new Map();
+    /** How many frames this connection has minted an id for. */
+    let downgrades = 0;
+    const hint = (event, payload) => {
+        const downgraded = event.type !== "message.changed" || payload.deltaDeclined === true;
+        if (downgraded)
+            downgrades += 1;
+        return write({
+            ...event,
+            // A frame this layer rewrote is a DIFFERENT frame -- another type, another
+            // payload -- and `id:` is what names one on the wire. Sending it under the
+            // source event's id had one id naming two frames, which a console that
+            // deduplicates by id would read as one. Derived from the source so it
+            // stays traceable, and unique per connection because that is the scope the
+            // id is read in.
+            ...(downgraded ? { id: `${event.id}#${String(downgrades)}` } : {}),
+            type: "message.changed",
+            // `deltaDeclined` is this layer's own signal and stops here.
+            payload: { messageId: payload.messageId, updatedAt: payload.updatedAt },
+        });
+    };
+    const rateLimited = (event, payload) => {
+        const key = event.threadId ?? "";
+        const at = now();
+        const last = hintedAt.get(key);
+        // Dropped, not queued: a hint says only that the message moved, so the one
+        // that was suppressed is answered by the one that follows it.
+        if (last !== undefined && at - last < DELTA_HINT_INTERVAL_MS)
+            return true;
+        // Delete before set, so insertion order IS recency order and the eviction
+        // below drops the conversation this connection heard about longest ago.
+        hintedAt.delete(key);
+        hintedAt.set(key, at);
+        while (hintedAt.size > MAX_THROTTLED_CONVERSATIONS) {
+            const oldest = hintedAt.keys().next();
+            if (oldest.done === true)
+                break;
+            hintedAt.delete(oldest.value);
+        }
+        return hint(event, payload);
+    };
+    return (event) => {
+        try {
+            if (event.type !== "message.delta" && event.type !== "message.changed")
+                return write(event);
+            const own = event.threadId !== undefined && event.threadId === subscribed;
+            if (event.type === "message.delta") {
+                const delta = requireMessageDelta(event.payload);
+                return own ? write(event) : rateLimited(event, delta);
+            }
+            const payload = requireMessageChanged(event.payload);
+            if (own)
+                return hint(event, payload);
+            if (subscribed === undefined && payload.deltaDeclined !== true)
+                return hint(event, payload);
+            return rateLimited(event, payload);
+        }
+        catch (error) {
+            // A frame this connection cannot make sense of is a server bug, and the
+            // honest answer is to end the stream so the console reconnects and
+            // bootstraps -- never to drop the frame and keep a live-looking socket.
+            onFailure?.(error);
+            close();
+            return false;
+        }
+    };
+}
+function requireMessageDelta(payload) {
+    const delta = payload;
+    if (delta === null || delta === undefined || typeof delta !== "object"
+        || typeof delta.messageId !== "string"
+        || typeof delta.updatedAt !== "string"
+        || typeof delta.baseSeq !== "number"
+        || typeof delta.seq !== "number"
+        || !Array.isArray(delta.ops)) {
+        throw new TypeError("A message.delta event carried no delta.");
+    }
+    return delta;
+}
+function requireMessageChanged(payload) {
+    const changed = payload;
+    if (changed === null || changed === undefined || typeof changed !== "object"
+        || typeof changed.messageId !== "string"
+        || typeof changed.updatedAt !== "string") {
+        throw new TypeError("A message.changed event named no message.");
+    }
+    return changed;
+}
 function requiredQueryString(value, field, max) {
     if (typeof value !== "string" || value.trim().length === 0 || value.length > max) {
         throw new WebConsoleError("invalid_page", `${field} is required.`, 400);
@@ -996,6 +1558,34 @@ function optionalSearchQuery(value, max) {
     }
     return value;
 }
+/**
+ * The conversation a console subscribes its event stream to.
+ *
+ * Its own code, not the pagination one: an invalid `?thread=` is a bad
+ * subscription, and answering it with "Pagination cursor is invalid." sent a
+ * console looking for a cursor it never sent.
+ */
+function optionalThreadSubscription(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string") {
+        throw invalidSubscription();
+    }
+    // The TRIMMED id is the subject of every rule here: it is what the dispatch
+    // compares against `event.threadId`, so it is what the length must bound and
+    // what is returned. Returning the padded string matched nothing and served
+    // hints for the conversation on screen.
+    const named = value.trim();
+    // Blank is refused rather than read as "no subscription": `?thread=` and
+    // `?thread=%20` are a console asking for a conversation and getting one it
+    // never named, which would look like the delta stream had simply stopped.
+    if (named.length === 0 || named.length > MAX_SUBSCRIPTION_LENGTH)
+        throw invalidSubscription();
+    return named;
+}
+function invalidSubscription() {
+    return new WebConsoleError("invalid_subscription", `thread must name one conversation, in at most ${String(MAX_SUBSCRIPTION_LENGTH)} characters.`, 400);
+}
 function optionalQueryString(value, max) {
     if (value === undefined)
         return undefined;
@@ -1004,6 +1594,35 @@ function optionalQueryString(value, max) {
     }
     return value;
 }
+/** `true`/`false`, or `undefined` for a query that said neither. */
+function optionalArchivedQuery(value) {
+    if (value === "true")
+        return true;
+    if (value === "false")
+        return false;
+    if (value === undefined)
+        return undefined;
+    throw new WebConsoleError("invalid_page", "archived must be true or false.", 400);
+}
+function optionalEmptyOnlyQuery(value) {
+    if (value === undefined)
+        return false;
+    if (value === "true")
+        return true;
+    throw new WebConsoleError("invalid_delete", "emptyOnly must be true when provided.", 400);
+}
+/**
+ * `?full=1` (or `full=true`) turns the transcript diet off for one read: no
+ * truncated tool payloads, no stripped telemetry. Anything else, including an
+ * absent parameter, keeps the shaped transcript.
+ *
+ * It changes the SHAPE of the messages a read answers with, never how many: a
+ * full conversation read still answers with one page and the rest still comes
+ * from `messagesNextCursor` (or an explicit `limit`).
+ */
+function fullTranscriptQuery(value) {
+    return value === "1" || value === "true" ? { full: true } : {};
+}
 function boundedQueryLimit(value, maximum, fallback) {
     if (value === undefined)
         return fallback;
@@ -1031,6 +1650,14 @@ function requireString(value, field, max, allowEmpty = false) {
 function optionalString(value, field, max) {
     return value === undefined ? undefined : requireString(value, field, max);
 }
+/** Optional override field: absent (`undefined`), cleared (`null`), or a bounded string. */
+function optionalNullableString(value, field, max) {
+    if (value === undefined)
+        return undefined;
+    if (value === null)
+        return null;
+    return requireString(value, field, max);
+}
 function invalidBody(message) {
     return new WebConsoleError("invalid_request", message, 400);
 }