@songsid/agend 2.1.12 → 2.2.0-alpha.2

package/dist/web-api.js

@@ -1,3 +1,17 @@
+import { settingsRequestExecution, settingsWrite, isSettingsReplay } from "./settings-request-capability.js";
+import { readBoundedWebBody } from "./web-body.js";
+import { gatewayRequestContext } from "./web-request-context.js";
+import { permitWebContinuation } from "./web-continuation.js";
+/**
+ * Web UI HTTP API handler.
+ * All /ui/* routes are handled here, extracted from fleet-manager.ts.
+ */
+import { formatWebChannelEcho } from "./web-channel-echo.js";
+import { t } from "./locale.js";
+import { isSafeInstanceName } from "./web-shell-routes.js";
+import { MAX_COMMAND_ARGS } from "./web-commands.js";
+import { sendPanelHtml } from "./web-host-guard.js";
+import { shellRoute } from "./web-shell-routes.js";
 import { readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -5,8 +19,12 @@ import { execFileSync } from "node:child_process";
 import { CreateInstanceArgs, validateArgs } from "./outbound-schemas.js";
 import { readStatuslineModel, resolveInstanceContext } from "./topic-commands.js";
 import { z } from "zod";
-import { isWebRequestAuthorized, WEB_TOKEN_INVALID_MESSAGE } from "./web-auth.js";
+import { evaluateWebRequest, isPassiveWebRead, isSecureRequest, isWebRequestAuthorized, WEB_TOKEN_INVALID_MESSAGE } from "./web-auth.js";
+import { newWebMessageId, parseLastEventId } from "./web-chat-history.js";
+import { attachmentDelivery, displayName, INLINE_MIME, isFileId, publicAttachment, sniffUpload, UPLOAD_LIMITS, wellFormed } from "./web-upload.js";
+import { getAgendHome } from "./paths.js";
 import { authorizeExplicitInstanceRemoval } from "./instance-removal.js";
+import { measureSyncWork } from "./sync-work-attribution.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.
@@ -51,16 +69,20 @@ const ConfigUpdateSchema = z.object({
 }).strict();
 const SendMessageSchema = z.object({
     instance: z.string().min(1).max(128),
-    message: z.string().min(1).max(MAX_TEXT),
-}).strict();
+    message: z.string().max(MAX_TEXT),
+    /** Ids from POST /ui/upload, for this instance, not yet sent. */
+    attachments: z.array(z.string().regex(/^[0-9a-f]{32}$/)).max(UPLOAD_LIMITS.maxFiles).optional(),
+}).strict().refine(v => v.message.trim().length > 0 || (v.attachments?.length ?? 0) > 0, { message: "a message or at least one file", path: ["message"] });
+/** An instance name that is safe as one path segment (no separator, no NUL, not a dot name). */
+const safeInstanceSegment = (name) => /^[^\\/\x00]+$/.test(name) && name !== "." && name !== "..";
 /**
  * Push a single SSE frame to every client. If a client throws (closed socket
  * after a network drop, etc.), evict it from the set and continue — without
  * the eviction the dead entry leaks forever, and without the try/catch a
  * single dead client breaks delivery to every client iterated after it.
  */
-export function broadcastSseEvent(clients, event, data, onError) {
-    const payload = `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
+export function broadcastSseEvent(clients, event, data, onError, id) {
+    const payload = sseFrame(event, data, id);
     const dead = [];
     for (const client of clients) {
         try {
@@ -79,6 +101,10 @@ export function broadcastSseEvent(clients, event, data, onError) {
         catch { /* socket already gone */ }
     }
 }
+/** One SSE frame; `id` (a chat message's) lets a reconnecting EventSource say what it last saw. */
+export function sseFrame(event, data, id) {
+    return `${id !== undefined ? `id: ${id}\n` : ""}event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
+}
 function parseOrReject(schema, data, res) {
     const r = schema.safeParse(data);
     if (!r.success) {
@@ -91,20 +117,11 @@ function parseOrReject(schema, data, res) {
 }
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
+/** How often a stream is refreshed, and how often it re-checks that its session still stands. */
+export const SSE_HEARTBEAT_MS = 10_000;
 /** Parse JSON body from request. */
-function parseBody(req) {
-    return new Promise((resolve, reject) => {
-        let body = "";
-        req.on("data", (chunk) => { body += chunk.toString(); });
-        req.on("end", () => {
-            try {
-                resolve(JSON.parse(body));
-            }
-            catch {
-                reject(new Error("Invalid JSON"));
-            }
-        });
-    });
+async function parseBody(req) {
+    return JSON.parse((await readBoundedWebBody(req, 512 * 1024)).toString("utf8"));
 }
 /** Send JSON response. */
 function json(res, status, data) {
@@ -119,11 +136,22 @@ export function handleWebRequest(req, res, url, ctx) {
     const path = url.pathname;
     const method = req.method ?? "GET";
     // Auth check for all /ui routes. Defence in depth behind the fleet-manager
-    // gate, which has already redeemed any `?token=` for a session cookie — so
-    // this accepts the cookie and the header too, and an unset token closes the
-    // panel instead of comparing null against a missing credential.
+    // gate: the same session cookie or header token, and an unset token closes
+    // the panel instead of comparing null against a missing credential.
     if (path.startsWith("/ui")) {
-        if (!isWebRequestAuthorized(req, url, ctx.webToken)) {
+        const approved = isSettingsReplay(req) && method === "POST"
+            && (path === "/ui/config" || path === "/ui/instances" || /^\/ui\/instances\/[^/]+\/delete$/.test(path))
+            ? settingsRequestExecution(req) : undefined;
+        if (approved) {
+            try {
+                approved.assert();
+            }
+            catch {
+                json(res, 409, { error: "settings_execution_stale" });
+                return true;
+            }
+        }
+        else if (!isWebRequestAuthorized(req, url, ctx.webToken, ctx.webSessions, { touch: !isPassiveWebRead(method, path) })) {
             json(res, 401, { error: WEB_TOKEN_INVALID_MESSAGE });
             return true;
         }
@@ -132,16 +160,16 @@ export function handleWebRequest(req, res, url, ctx) {
         return false;
     }
     // ── Static files ───────────────────────────────────────
-    if (method === "GET" && path === "/ui") {
-        try {
-            const html = readFileSync(join(__dirname, "ui", "dashboard.html"), "utf-8");
-            res.setHeader("Content-Type", "text/html; charset=utf-8");
-            res.writeHead(200);
-            res.end(html);
-        }
-        catch {
-            json(res, 500, { error: "dashboard.html not found" });
-        }
+    // #1408: the app shell, for exactly the paths the classifier names (src/web-shell-routes.ts). One page for every
+    // route; the client router mounts the panel. A malformed instance name is a 400, an unknown one is the shell (the
+    // panel says "not found"), so the response never tells which names exist.
+    const shell = shellRoute(method, path);
+    if (shell?.kind === "malformed") {
+        json(res, 400, { error: "invalid instance name" });
+        return true;
+    }
+    if (shell?.kind === "shell") {
+        serveAppShell(req, res, ctx, "full");
         return true;
     }
     // Serve JS modules
@@ -190,22 +218,83 @@ export function handleWebRequest(req, res, url, ctx) {
         return true;
     }
     // ── SSE ────────────────────────────────────────────────
+    // The same data as the stream, over plain requests, for a path that cannot carry SSE (Cloudflare Quick
+    // Tunnels do not; a buffering proxy looks like a mute server). `after` is the same `<boot>-<id>` cursor
+    // as the stream's Last-Event-ID, so polling and the stream can take turns without a message twice or
+    // a gap — and a cursor from before a fleet restart gets the new process's backlog. No cursor yet (the page
+    // has not seen a single stream message): everything still retained, like a restart's backlog, so a message
+    // that arrived while the stream was silent is not skipped by the cursor this answer hands out (#1251
+    // review). The page keeps one entry per boot+id, so what it already loaded from /ui/history is not doubled.
+    if (method === "GET" && path === "/ui/poll") {
+        const history = ctx.webChatHistory;
+        const after = url.searchParams.get("after");
+        const fresh = after === null || after === ""; // a cursor that is not ours in shape still gets nothing
+        json(res, 200, {
+            status: ctx.getUiStatus(),
+            messages: history ? (fresh ? history.after(0) : history.replayFor(parseLastEventId(after))) : [],
+            // The ticks too, so polling never has to re-read a chat's history — that read would count as the person's
+            // activity; this poll does not (isPassiveWebRead).
+            deliveries: history ? history.deliveries() : [],
+            // And the fleet prompts open on the dashboard (C4): prompt events are stream-only too.
+            prompts: ctx.listWebPrompts?.() ?? [],
+            // #1386: "Needs you" rides the passive channels only — no endpoint of its own to poll.
+            needs: ctx.needsYouItems?.() ?? [],
+            cursor: history ? `${history.boot}-${history.lastId}` : null,
+        });
+        return true;
+    }
     if (method === "GET" && path === "/ui/events") {
+        if (gatewayRequestContext(req)) {
+            json(res, 404, { error: "Use polling on the public link" });
+            return true;
+        }
         res.writeHead(200, {
             "Content-Type": "text/event-stream",
             "Cache-Control": "no-cache",
             Connection: "keep-alive",
         });
         res.write(`event: status\ndata: ${JSON.stringify(ctx.getUiStatus())}\n\n`);
+        // An EventSource that reconnects says what it last saw: send what it missed, before anything new.
+        const lastSeen = parseLastEventId(req.headers["last-event-id"]);
+        if (lastSeen !== null && ctx.webChatHistory) {
+            const history = ctx.webChatHistory;
+            for (const m of history.replayFor(lastSeen))
+                res.write(sseFrame("message", m, history.cursorOf(m)));
+        }
+        // Ticks change messages already sent and carry no cursor: every (re)connect gets where each one is now, so a
+        // report that fell into a gap is not lost until a reload (#1253 review). No id: it is not a message.
+        if (ctx.webChatHistory)
+            res.write(`event: deliveries\ndata: ${JSON.stringify(ctx.webChatHistory.deliveries())}\n\n`);
+        // The same for the fleet prompts (C4): one posted, answered or expired during a gap is caught up here.
+        if (ctx.listWebPrompts)
+            res.write(`event: prompts\ndata: ${JSON.stringify(ctx.listWebPrompts())}\n\n`);
+        // #1386: and "Needs you" as it is now; changes follow as `needs` events.
+        if (ctx.needsYouItems)
+            res.write(`event: needs\ndata: ${JSON.stringify({ items: ctx.needsYouItems() })}\n\n`);
         ctx.sseClients.add(res);
         const interval = setInterval(() => {
+            // A stream authorized once must not outlive the authorization. Re-checked
+            // without counting as activity, or an open tab would keep an idle session
+            // alive forever; a revoked, expired or rotated-away session ends here.
+            if (!isWebRequestAuthorized(req, url, ctx.webToken, ctx.webSessions, { touch: false })) {
+                // Close the connection too, not just the response: an ended response leaves the socket idle in
+                // keep-alive, still held open by whoever's session just ended.
+                const socket = req.socket;
+                try {
+                    res.end(() => socket?.destroy());
+                }
+                catch { /* already closed */ }
+                cleanup();
+                return;
+            }
             try {
-                res.write(`event: status\ndata: ${JSON.stringify(ctx.getUiStatus())}\n\n`);
+                // Every open dashboard tab, every 10 s: the status of every instance, serialized on the fleet's loop (#1235).
+                res.write(measureSyncWork("web.sseStatus", () => `event: status\ndata: ${JSON.stringify(ctx.getUiStatus())}\n\n`));
             }
             catch {
                 cleanup();
             }
-        }, 10_000);
+        }, ctx.sseHeartbeatMs ?? SSE_HEARTBEAT_MS);
         let cleanedUp = false;
         const cleanup = () => {
             if (cleanedUp)
@@ -214,20 +303,216 @@ export function handleWebRequest(req, res, url, ctx) {
             ctx.sseClients.delete(res);
             clearInterval(interval);
         };
-        // `close` covers normal disconnects; `error` covers network resets that
-        // never deliver a clean FIN. Without both, dead clients accumulate in
+        // The *response's* `close` is the one that means the stream is over: it fires when the connection
+        // goes away or the response is finished. The request's `close` means "the request has been read"
+        // — on newer Node that can be as soon as it is consumed, which would drop a live stream from
+        // sseClients and stop its session re-check while the response is still open. `error` covers
+        // network resets that never deliver a clean FIN. Without these, dead clients accumulate in
         // sseClients and the heartbeat interval keeps firing forever.
-        req.on("close", cleanup);
+        res.on("close", cleanup);
         req.on("error", cleanup);
         res.on("error", cleanup);
         return true;
     }
+    // ── Chat history ───────────────────────────────────────
+    if (method === "GET" && path === "/ui/history") {
+        const instance = url.searchParams.get("instance") ?? "";
+        const limitRaw = url.searchParams.get("limit");
+        const limit = limitRaw === null ? 200 : Number(limitRaw);
+        if (instance.length === 0 || instance.length > 128 || !Number.isInteger(limit) || limit < 1 || limit > 500) {
+            json(res, 400, { error: "instance (1-128 chars) and limit (1-500) required" });
+            return true;
+        }
+        json(res, 200, { messages: ctx.webChatHistory?.list(instance, limit) ?? [], boot: ctx.webChatHistory?.boot ?? null, lastId: ctx.webChatHistory?.lastId ?? 0 });
+        return true;
+    }
     // ── Send message ───────────────────────────────────────
     if (method === "POST" && path === "/ui/send") {
         handleSendMessage(req, res, ctx);
         return true;
     }
+    // ── Files (C2): upload one file for an instance; fetch a file by the id the fleet issued for it ──
+    if (method === "POST" && path === "/ui/upload") {
+        handleUpload(req, res, url, ctx);
+        return true;
+    }
+    const fileMatch = path.match(/^\/ui\/file\/([^/]+)$/);
+    if (method === "GET" && fileMatch) {
+        const id = fileMatch[1];
+        const got = isFileId(id) ? ctx.webFiles?.read(id) : null;
+        if (!got) {
+            json(res, 404, { error: "No such file" });
+            return true;
+        }
+        const { file, bytes } = got;
+        const inline = INLINE_MIME.has(file.mime);
+        // Only the four image types are shown in the page; anything else is a download, never rendered.
+        res.setHeader("Content-Type", inline ? file.mime : (file.mime.startsWith("text/") ? "text/plain; charset=utf-8" : "application/octet-stream"));
+        res.setHeader("Content-Disposition", `${inline ? "inline" : "attachment"}; filename*=UTF-8''${encodeURIComponent(wellFormed(file.name))}`);
+        res.setHeader("X-Content-Type-Options", "nosniff");
+        res.setHeader("Cache-Control", "private, no-store");
+        res.setHeader("Content-Security-Policy", "default-src 'none'; img-src 'self'; style-src 'unsafe-inline'; sandbox");
+        res.writeHead(200);
+        res.end(bytes);
+        return true;
+    }
+    // ── Fleet prompts (C4): the hang / exit / interactive-prompt buttons, answerable here too ──
+    if (method === "GET" && path === "/ui/prompts") {
+        json(res, 200, { prompts: ctx.listWebPrompts?.() ?? [] });
+        return true;
+    }
+    // The nonce is the capability, so it travels in the body: never in a URL a log or a history could keep.
+    if (method === "POST" && path === "/ui/prompt") {
+        if (!ctx.clickWebPrompt) {
+            json(res, 404, { error: "No prompts here" });
+            return true;
+        }
+        const click = ctx.clickWebPrompt.bind(ctx);
+        (async () => {
+            let body;
+            try {
+                body = await parseBody(req);
+            }
+            catch {
+                json(res, 400, { error: "Invalid JSON" });
+                return;
+            }
+            if (!permitWebContinuation(req, res, ctx))
+                return;
+            if (!body || typeof body !== "object") {
+                json(res, 400, { error: "instance, nonce and action required" });
+                return;
+            }
+            const { instance, nonce, action } = body;
+            if (typeof instance !== "string" || typeof nonce !== "string" || typeof action !== "string") {
+                json(res, 400, { error: "instance, nonce and action required" });
+                return;
+            }
+            const r = await click(instance, nonce, action);
+            // 409: answered elsewhere first, expired, or never open — the page drops the buttons on `gone`.
+            json(res, r.status, r.status === 200 ? { answered: true } : { error: r.error ?? "Refused", ...(r.status === 409 ? { gone: true } : {}) });
+        })().catch(err => {
+            ctx.logger.error({ err: err.message }, "Web prompt answer failed");
+            try {
+                json(res, 500, { error: "Prompt answer failed" });
+            }
+            catch { /* already answered */ }
+        });
+        return true;
+    }
+    // #1386: Acknowledge a "Needs you" delivery item — a session write (CSRF, checked by the gate) or the CLI's header
+    // token. Who did it is recorded by principal: the session's public handle, never the session id or a credential.
+    if (method === "POST" && path === "/ui/needs/ack") {
+        if (!ctx.acknowledgeNeedsItem) {
+            json(res, 404, { error: "Nothing to acknowledge here" });
+            return true;
+        }
+        const acknowledge = ctx.acknowledgeNeedsItem.bind(ctx);
+        (async () => {
+            let body;
+            try {
+                body = await parseBody(req);
+            }
+            catch {
+                json(res, 400, { error: "Invalid JSON" });
+                return;
+            }
+            if (!permitWebContinuation(req, res, ctx))
+                return;
+            const id = body && typeof body === "object" ? body.id : undefined;
+            if (typeof id !== "string") {
+                json(res, 400, { error: "id required" });
+                return;
+            }
+            const verdict = evaluateWebRequest(req, url, ctx.webToken ?? null, ctx.webSessions, { touch: false });
+            if (verdict.kind !== "allow") {
+                json(res, 401, { error: WEB_TOKEN_INVALID_MESSAGE });
+                return;
+            }
+            const principal = verdict.via === "session" && verdict.session ? `web:${verdict.session.handle}` : "cli";
+            const r = acknowledge(id, principal);
+            json(res, r.status, r.status === 200 ? { acknowledged: true, message: r.message } : { error: r.message });
+        })().catch(err => {
+            ctx.logger.error({ err: err.message }, "Needs you acknowledge failed");
+            try {
+                json(res, 500, { error: "Acknowledge failed" });
+            }
+            catch { /* already answered */ }
+        });
+        return true;
+    }
+    // #1269: an instance's chat command (/ctx, /compact, /clear, /model, …) — a session write (CSRF, checked by the
+    // gate), run through the platforms' own handlers and command table. The public link is told it is one (/save is
+    // refused there).
+    if (method === "POST" && path === "/ui/command") {
+        if (!ctx.webCommand) {
+            json(res, 404, { error: "Not available" });
+            return true;
+        }
+        const run = ctx.webCommand.bind(ctx);
+        (async () => {
+            let body;
+            try {
+                body = await parseBody(req);
+            }
+            catch {
+                json(res, 400, { error: "Invalid JSON" });
+                return;
+            }
+            if (!permitWebContinuation(req, res, ctx))
+                return;
+            const str = (v, max) => (typeof v === "string" && v.length <= max ? v : undefined);
+            const instance = str(body?.instance, 128), command = str(body?.command, 32);
+            if (!instance || !isSafeInstanceName(instance) || !command) {
+                json(res, 400, { error: "instance and command required" });
+                return;
+            }
+            if (body.args !== undefined && str(body.args, MAX_COMMAND_ARGS) === undefined) {
+                json(res, 400, { error: "args too long" });
+                return;
+            }
+            if (body.confirm !== undefined && !(typeof body.confirm === "string" && /^[0-9a-f]{32}$/.test(body.confirm))) {
+                json(res, 400, { error: "invalid confirmation" });
+                return;
+            }
+            const r = await run({ instance, command, args: str(body.args, MAX_COMMAND_ARGS), confirm: body.confirm }, { publicLink: !!gatewayRequestContext(req) });
+            json(res, r.status, r.body);
+        })().catch(err => {
+            ctx.logger.error({ err: err.message }, "Web command failed");
+            try {
+                json(res, 500, { error: "Command failed" });
+            }
+            catch { /* already answered */ }
+        });
+        return true;
+    }
     // ── Instance operations ────────────────────────────────
+    // Stop the agent's current reply — what Telegram's cancel button and /cancel do: Esc into the CLI, and the
+    // messages still waiting for it are dropped. Not /ui/stop, which stops the instance's process.
+    const cancelMatch = path.match(/^\/ui\/cancel\/([^/]+)$/);
+    if (method === "POST" && cancelMatch) {
+        let name;
+        try {
+            name = decodeURIComponent(cancelMatch[1]);
+        }
+        catch {
+            json(res, 400, { error: "Bad instance name" });
+            return true;
+        }
+        // Own keys only: "constructor" is in every object and names no instance.
+        const known = (ctx.fleetConfig ? Object.hasOwn(ctx.fleetConfig.instances, name) : false) || ctx.daemons.has(name);
+        if (!ctx.cancelInstance || !known) {
+            json(res, 404, { error: `Instance not found: ${name}` });
+            return true;
+        }
+        if (!ctx.cancelInstance(name)) {
+            json(res, 409, { error: `${name} is not running` });
+            return true;
+        }
+        ctx.eventLog?.logActivity("cancel", "web-user", "stop the current reply", name);
+        json(res, 200, { cancelled: name });
+        return true;
+    }
     const stopMatch = path.match(/^\/ui\/stop\/(.+)$/);
     if (method === "POST" && stopMatch) {
         const name = decodeURIComponent(stopMatch[1]);
@@ -278,11 +563,17 @@ export function handleWebRequest(req, res, url, ctx) {
         (async () => {
             try {
                 const body = await parseBody(req);
+                if (!permitWebContinuation(req, res, ctx))
+                    return;
                 if (body.confirm !== `delete ${name}`) {
                     json(res, 400, { error: `Confirmation required: { "confirm": "delete ${name}" }` });
                     return;
                 }
-                await ctx.removeInstance(name, authorizeExplicitInstanceRemoval("dashboard-confirmed"));
+                const execution = settingsRequestExecution(req);
+                if (execution)
+                    await ctx.removeInstance(name, authorizeExplicitInstanceRemoval("dashboard-confirmed"), execution);
+                else
+                    await ctx.removeInstance(name, authorizeExplicitInstanceRemoval("dashboard-confirmed"));
                 ctx.emitSseEvent("status", ctx.getUiStatus());
                 json(res, 200, { deleted: name });
             }
@@ -364,6 +655,8 @@ export function handleWebRequest(req, res, url, ctx) {
         (async () => {
             try {
                 const body = await parseBody(req);
+                if (!permitWebContinuation(req, res, ctx))
+                    return;
                 const v = validateArgs(CreateInstanceArgs, body, "create_instance");
                 if (!v.ok) {
                     json(res, 400, { error: v.error });
@@ -371,7 +664,12 @@ export function handleWebRequest(req, res, url, ctx) {
                 }
                 let result = null;
                 let error;
-                await ctx.lifecycle.handleCreate(v.data, (r, e) => { result = r; error = e; });
+                const respond = (r, e) => { result = r; error = e; };
+                const execution = settingsRequestExecution(req);
+                if (execution)
+                    await ctx.lifecycle.handleCreate(v.data, respond, undefined, execution);
+                else
+                    await ctx.lifecycle.handleCreate(v.data, respond);
                 if (error) {
                     json(res, 400, { error });
                 }
@@ -404,6 +702,8 @@ export function handleWebRequest(req, res, url, ctx) {
         (async () => {
             try {
                 const body = await parseBody(req);
+                if (!permitWebContinuation(req, res, ctx))
+                    return;
                 const parsed = parseOrReject(TaskCreateSchema, body, res);
                 if (!parsed)
                     return;
@@ -432,6 +732,8 @@ export function handleWebRequest(req, res, url, ctx) {
         (async () => {
             try {
                 const body = await parseBody(req);
+                if (!permitWebContinuation(req, res, ctx))
+                    return;
                 const parsed = parseOrReject(TaskUpdateSchema, body, res);
                 if (!parsed)
                     return;
@@ -472,6 +774,8 @@ export function handleWebRequest(req, res, url, ctx) {
         (async () => {
             try {
                 const body = await parseBody(req);
+                if (!permitWebContinuation(req, res, ctx))
+                    return;
                 const parsed = parseOrReject(ScheduleCreateSchema, body, res);
                 if (!parsed)
                     return;
@@ -499,7 +803,23 @@ export function handleWebRequest(req, res, url, ctx) {
         }
         return true;
     }
+    // #1468: the prompt-cache expiry analysis. Opening it is a person's navigation, like any Fleet tab (it counts as
+    // use); the page never re-reads it on a timer. Answered from the ledgers as they are; a catch-up runs behind.
+    if (method === "GET" && path === "/ui/cache") {
+        if (!ctx.cacheReport) {
+            json(res, 404, { error: "Not available" });
+            return true;
+        }
+        ctx.cacheReport(url.searchParams.get("window") ?? "7d").then((report) => json(res, 200, report), (err) => { ctx.logger.error({ err }, "cache analysis failed"); json(res, 500, { error: "Cache analysis failed" }); });
+        return true;
+    }
     // ── Teams ──────────────────────────────────────────────
+    // #1389: the org chart. Opening it is a person's navigation (it counts as use, like a Fleet tab); nothing re-reads
+    // it on a timer — the live state comes over the stream the page already has.
+    if (method === "GET" && path === "/ui/org") {
+        json(res, 200, ctx.orgChart?.() ?? { general: [], teams: [], instances: {} });
+        return true;
+    }
     if (method === "GET" && path === "/ui/teams") {
         const teams = ctx.fleetConfig?.teams ?? {};
         json(res, 200, { teams });
@@ -509,6 +829,8 @@ export function handleWebRequest(req, res, url, ctx) {
         (async () => {
             try {
                 const body = await parseBody(req);
+                if (!permitWebContinuation(req, res, ctx))
+                    return;
                 const parsed = parseOrReject(TeamCreateSchema, body, res);
                 if (!parsed)
                     return;
@@ -569,6 +891,8 @@ export function handleWebRequest(req, res, url, ctx) {
         (async () => {
             try {
                 const body = await parseBody(req);
+                if (!permitWebContinuation(req, res, ctx))
+                    return;
                 const parsed = parseOrReject(ConfigUpdateSchema, body, res);
                 if (!parsed)
                     return;
@@ -578,26 +902,28 @@ export function handleWebRequest(req, res, url, ctx) {
                     return;
                 }
                 const ch = config.channel;
-                // Update channel settings
-                if (parsed.channel && ch) {
-                    if (parsed.channel.group_id != null)
-                        config.channel.group_id = parsed.channel.group_id;
-                    if (parsed.channel.access)
-                        config.channel.access = parsed.channel.access;
-                }
-                // Update defaults
-                if (parsed.defaults) {
-                    const d = config.defaults;
-                    if (parsed.defaults.backend)
-                        d.backend = parsed.defaults.backend;
-                    if (parsed.defaults.model)
-                        d.model = parsed.defaults.model;
-                }
-                // Update project_roots
-                if (parsed.project_roots) {
-                    config.project_roots = parsed.project_roots;
-                }
-                ctx.saveFleetConfig();
+                settingsWrite(req, () => {
+                    // Update channel settings
+                    if (parsed.channel && ch) {
+                        if (parsed.channel.group_id != null)
+                            config.channel.group_id = parsed.channel.group_id;
+                        if (parsed.channel.access)
+                            config.channel.access = parsed.channel.access;
+                    }
+                    // Update defaults
+                    if (parsed.defaults) {
+                        const d = config.defaults;
+                        if (parsed.defaults.backend)
+                            d.backend = parsed.defaults.backend;
+                        if (parsed.defaults.model)
+                            d.model = parsed.defaults.model;
+                    }
+                    // Update project_roots
+                    if (parsed.project_roots) {
+                        config.project_roots = parsed.project_roots;
+                    }
+                    ctx.saveFleetConfig();
+                });
                 const needsRestart = parsed.channel?.group_id != null;
                 json(res, 200, { saved: true, needs_restart: needsRestart });
             }
@@ -611,6 +937,14 @@ export function handleWebRequest(req, res, url, ctx) {
     json(res, 404, { error: "not found" });
     return true;
 }
+/** Keep the echo in a single platform message, including its attachment names. */
+function webEchoPreview(message, names) {
+    const text = wellFormed(message.slice(0, 500));
+    const files = names.length ? `[📎 ${names.map(name => displayName(name, "attachment")).join(", ")}]` : "";
+    const preview = [text, files].filter(Boolean).join(" ");
+    const truncated = message.length > 500 || preview.length > 1400;
+    return wellFormed(preview.slice(0, 1400)) + (truncated ? ` … (${t("web.echo_full_text")})` : "");
+}
 /** Handle POST /ui/send — extracted for readability. */
 function handleSendMessage(req, res, ctx) {
     let body = "";
@@ -625,6 +959,8 @@ function handleSendMessage(req, res, ctx) {
         body += chunk.toString();
     });
     req.on("end", async () => {
+        if (!permitWebContinuation(req, res, ctx))
+            return;
         try {
             const raw = JSON.parse(body);
             const parsed = SendMessageSchema.safeParse(raw);
@@ -633,55 +969,199 @@ function handleSendMessage(req, res, ctx) {
                 json(res, 400, { error: `${issue.path.join(".") || "body"}: ${issue.message}` });
                 return;
             }
-            const { instance, message } = parsed.data;
+            const { instance, message: typed, attachments = [] } = parsed.data;
             const ipc = ctx.instanceIpcClients.get(instance);
             if (!ipc) {
                 json(res, 404, { error: `Instance not found: ${instance}` });
                 return;
             }
+            let files = [];
+            if (attachments.length > 0) {
+                const taken = ctx.webFiles?.takeForMessage(instance, attachments);
+                if (!taken || !taken.ok) {
+                    json(res, 400, { error: taken && !taken.ok ? taken.error : "files are not available here" });
+                    return;
+                }
+                files = taken.entries;
+            }
+            // The same tags and meta a Telegram photo/document produces, so the agent needs nothing new.
+            const delivery = attachmentDelivery(typed, files);
+            // #1269: `/raw ` is pasted into the CLI with no [user:] envelope (the daemon's own check, on this exact text).
+            // A signed-in local session may do that, as a fleet admin on the platform may; the public link — the outward-
+            // facing surface — may not.
+            if (gatewayRequestContext(req) && delivery.text.startsWith("/raw ")) {
+                ctx.webFiles?.release(files);
+                json(res, 403, { error: t("web.raw_public_refused") });
+                return;
+            }
+            const message = typed;
             const ts = new Date().toISOString();
+            // The id the agent is given, and the one its delivery reports come back under: the page's ticks.
+            const messageId = newWebMessageId();
             // Use real Telegram context so daemon's lastChatId/lastThreadId are set,
             // enabling reply tool even when first message comes from Web UI.
-            // Pure Web UI mode (no channel config) leaves these empty — TODO: needs
-            // a separate reply path for that case.
-            const groupId = ctx.fleetConfig?.channel?.group_id;
+            // Pure Web UI mode (no channel config) leaves these empty; the agent's reply then comes back to the
+            // web chat alone (FleetManager's web-only reply sink).
+            const syncAdapter = ctx.getAdapterForInstance ? ctx.getAdapterForInstance(instance) : ctx.adapter;
+            const groupId = ctx.getGroupIdForInstance?.(instance) ?? String(ctx.fleetConfig?.channel?.group_id ?? "");
             const topicId = ctx.fleetConfig?.instances[instance]?.topic_id;
+            const canEcho = ctx.fleetConfig?.web?.echo_to_channel !== false
+                && !ctx.isClassicInstance?.(instance) && syncAdapter && groupId && topicId != null;
+            // Add no runtime credentials or local attachment paths to the display copy.
+            const preview = webEchoPreview(message, files.map(f => f.name));
+            // ClassicBot echo (#1320 part B): same ordering lane, per-entry
+            // opt-in resolved at send time inside sendClassicWebEcho.
+            const canClassicEcho = ctx.isClassicInstance?.(instance) === true && !!ctx.sendClassicWebEcho;
+            const settleClassicEcho = canClassicEcho ? ctx.reserveWebChannelEcho?.(instance, async () => {
+                await ctx.sendClassicWebEcho(instance, formatWebChannelEcho("web-user", preview, t("web.echo_full_text")));
+            }) : undefined;
+            const settleEcho = canEcho ? ctx.reserveWebChannelEcho?.(instance, async () => {
+                // A replacement adapter or edited binding is not the route we reserved.
+                if ((ctx.getAdapterForInstance ? ctx.getAdapterForInstance(instance) : ctx.adapter) !== syncAdapter
+                    || (ctx.getGroupIdForInstance?.(instance) ?? String(ctx.fleetConfig?.channel?.group_id ?? "")) !== groupId
+                    || ctx.fleetConfig?.instances[instance]?.topic_id !== topicId)
+                    return;
+                return syncAdapter.sendText(String(groupId), formatWebChannelEcho("web-user", preview, t("web.echo_full_text")), { threadId: String(topicId), format: "text", allowedMentions: { parse: [] } });
+            }) : undefined;
+            let delivered;
             try {
-                await ctx.deliverToInstance(instance, {
+                delivered = await ctx.deliverToInstance(instance, {
                     type: "fleet_inbound",
-                    content: message,
+                    content: delivery.text,
                     targetSession: instance,
                     meta: {
                         chat_id: groupId ? String(groupId) : "",
-                        message_id: `web-${Date.now()}`,
+                        message_id: messageId,
                         user: "web-user", user_id: "web-user",
                         ts,
                         thread_id: topicId != null ? String(topicId) : "",
                         source: "web",
+                        adapter_id: syncAdapter?.id,
+                        ...delivery.meta,
                     },
                 });
             }
             catch (err) {
+                settleEcho?.(false);
+                // A throw must release the Classic ordering lane too: otherwise the
+                // next accepted echo queues behind a reservation that never settles
+                // and is dropped by expiry (#1330 R2).
+                settleClassicEcho?.(false);
+                ctx.webFiles?.release(files); // not delivered: the same ids can be sent again
                 ctx.logger.error({ err, instance }, "Web message delivery failed");
                 json(res, 503, { error: "Instance delivery failed" });
                 return;
             }
+            if (delivered === false) {
+                settleEcho?.(false);
+                settleClassicEcho?.(false);
+                ctx.webFiles?.release(files);
+                ctx.logger.error({ instance }, "Web message not delivered (the instance went away or restarted)");
+                json(res, 503, { error: "Instance delivery failed" });
+                return;
+            }
+            settleEcho?.(true);
+            settleClassicEcho?.(true);
+            ctx.webFiles?.commit(files);
             ctx.lastInboundUser.set(instance, "web-user");
-            ctx.eventLog?.logActivity("message", "web-user", message.slice(0, 200), instance);
-            ctx.emitSseEvent("message", { instance, sender: "web-user", text: message, ts });
-            // Sync to Telegram/Discord
-            const syncAdapter = ctx.getAdapterForInstance?.(instance) ?? ctx.adapter;
-            const syncGroupId = ctx.getGroupIdForInstance?.(instance) ?? String(ctx.fleetConfig?.channel?.group_id ?? "");
-            if (syncAdapter && syncGroupId) {
-                const topicId = ctx.fleetConfig?.instances[instance]?.topic_id;
-                const preview = message.length > 500 ? message.slice(0, 500) + " [...]" : message;
-                syncAdapter.sendText(syncGroupId, `🌐 web-user: ${preview}`, { threadId: topicId != null ? String(topicId) : undefined }).catch(() => ctx.logger.debug({}, "Web→Channel sync failed"));
-            }
-            json(res, 200, { sent: true });
+            ctx.eventLog?.logActivity("message", "web-user", (message || `[${files.length} file(s)]`).slice(0, 200), instance);
+            ctx.emitSseEvent("message", { instance, sender: "web-user", role: "user", text: message, ts, attachments: files.map(publicAttachment), messageId });
+            json(res, 200, { sent: true, messageId });
         }
         catch {
             json(res, 400, { error: "Invalid JSON" });
         }
     });
 }
+/**
+ * One file for one instance's chat. The body is the file itself (Content-Type is ignored: the type is
+ * read from the bytes), `X-Agend-Filename` its name for the label only. Stored in the instance's
+ * workspace inbox under a name chosen here; answered with the id the message will name.
+ */
+function handleUpload(req, res, url, ctx) {
+    const instance = url.searchParams.get("instance") ?? "";
+    if (!ctx.webFiles) {
+        json(res, 404, { error: "uploads are not available" });
+        return;
+    }
+    if (!instance || instance.length > 128 || !safeInstanceSegment(instance) || !ctx.instanceIpcClients.has(instance)) {
+        json(res, 404, { error: `Instance not found: ${instance}` });
+        return;
+    }
+    const declared = Number(req.headers["content-length"] ?? NaN);
+    if (Number.isFinite(declared) && declared > UPLOAD_LIMITS.maxFileBytes) {
+        json(res, 413, { error: `a file can be at most ${UPLOAD_LIMITS.maxFileBytes / 1024 / 1024} MB` });
+        req.resume();
+        return;
+    }
+    const chunks = [];
+    let size = 0;
+    let refused = false;
+    req.on("data", (c) => {
+        if (refused)
+            return;
+        size += c.length;
+        if (size > UPLOAD_LIMITS.maxFileBytes) {
+            refused = true;
+            json(res, 413, { error: `a file can be at most ${UPLOAD_LIMITS.maxFileBytes / 1024 / 1024} MB` });
+            req.destroy();
+            return;
+        }
+        chunks.push(c);
+    });
+    req.on("error", () => { });
+    req.on("end", () => {
+        if (!permitWebContinuation(req, res, ctx))
+            return;
+        if (refused)
+            return;
+        const bytes = Buffer.concat(chunks);
+        const name = displayName(typeof req.headers["x-agend-filename"] === "string" ? req.headers["x-agend-filename"] : "", "file");
+        const type = sniffUpload(bytes, name);
+        if (!type) {
+            json(res, 415, { error: "unsupported file type — images (PNG, JPEG, GIF, WebP), PDF and text files only" });
+            return;
+        }
+        // The instance is checked again now the whole body is here: it may have been deleted (and its files
+        // forgotten) or stopped while the upload streamed in; storing now would bring its id back (#1252 review).
+        // Still deliverable means: its IPC is up (a paused one is woken by the send) and it is still registered —
+        // in fleet.yaml, or as a ClassicBot room in classicBot.yaml.
+        const registered = !!ctx.fleetConfig?.instances?.[instance] || ctx.isClassicInstance?.(instance) === true;
+        if (!ctx.instanceIpcClients.has(instance) || !registered) {
+            json(res, 404, { error: `Instance not found: ${instance}` });
+            return;
+        }
+        try {
+            const entry = ctx.webFiles.storeUpload({ instance, inboxDir: join(getAgendHome(), "workspaces", instance, "inbox"), bytes, name, type });
+            json(res, 200, publicAttachment(entry));
+        }
+        catch (err) {
+            ctx.logger.error({ err: err.message, instance }, "Web upload could not be stored");
+            json(res, 500, { error: "the file could not be stored" });
+        }
+    });
+}
+function shellPreview(req, ctx, mode) {
+    if (mode !== "full" || gatewayRequestContext(req))
+        return null;
+    return ctx.previewForUi?.(typeof req.headers.host === "string" ? req.headers.host : undefined, isSecureRequest(req)) ?? null;
+}
+function shellBodyTag(req, ctx, mode) {
+    const p = shellPreview(req, ctx, mode);
+    const attr = (v) => String(v ?? "").replace(/[&<>"']/g, c => `&#${c.charCodeAt(0)};`);
+    return `<body data-mode="${mode}"${mode === "full" && gatewayRequestContext(req) ? ' data-web-transport="poll"' : ""} data-dashboard-origin="${attr(p?.dashboardOrigin)}" data-preview-origin="${attr(p?.previewOrigin)}"`
+        + ` data-preview-boot="${attr(p?.previewOrigin ? p.boot : "")}" data-preview-reason="${attr(p ? p.reason : "Previews are not available on this fleet.")}">`;
+}
+/** The app shell page for one entry, under the panels' CSP; it may frame exactly <preview origin>/frame, and only
+ *  when this load chose one. */
+export function serveAppShell(req, res, ctx, mode) {
+    try {
+        const html = readFileSync(join(__dirname, "ui", "app.html"), "utf-8");
+        const p = shellPreview(req, ctx, mode);
+        sendPanelHtml(res, html.replace("<body>", shellBodyTag(req, ctx, mode)), 200, {}, p?.previewOrigin ? { frameSrc: `${p.previewOrigin}/frame` } : {});
+    }
+    catch {
+        json(res, 500, { error: "app.html not found" });
+    }
+}
 //# sourceMappingURL=web-api.js.map