@songsid/agend 2.2.0-alpha.1 → 2.2.0-alpha.3

package/dist/ui/preview-panel.js

@@ -0,0 +1,237 @@
+// #1481: an agent's HTML preview (#1306) in a panel beside the conversation — a split with a draggable divider on a
+// wide screen, a full-screen sheet on a narrow one. Nothing about the preview itself changes here: the frame is the one
+// preview.js makes (mountPreview: the preview origin, sandbox allow-scripts only), started by AgendPreview.start like a
+// card's, only told to fill the panel. It runs on a click, as a card's does:
+// - "Open in panel" on an idle card opens the panel with its Preview button — the panel runs nothing by itself;
+// - on a card whose preview is running, the same button moves that run to the panel (stopped in the card, started in
+//   the panel: a moved frame reloads anyway);
+// - a newer version of the block in a later reply is offered, never swapped in, and offered with Preview to click.
+// Closing the panel or leaving the chat stops its frame; one preview per page still holds (start() stops any other).
+import { html, useEffect, useRef, useState } from "/assets/app-html.js";
+import { t } from "/assets/app-i18n.js";
+import { Icon } from "/assets/ui-icons.js";
+import "./chat-render.js";
+import "./preview.js";
+import { loadHtmlAttachment } from "./html-attachment.js";
+
+const R = () => globalThis.AgendChatRender;
+const P = () => globalThis.AgendPreview;
+
+// ── The panel's state, one per page (the chat shows one instance at a time) ──
+
+/** open: { key, instance, msgKey, n | att, code, sender, ts } | null (`att`: an attached .html file, #1306 Q4); run: start it on mount (a moved run). */
+let state = { open: null, run: 0 };
+const subs = new Set();
+function set(next) { state = next; for (const fn of [...subs]) { try { fn(state); } catch { /* one listener's error stops no other */ } } }
+export const panelStore = { get: () => state, subscribe(fn) { subs.add(fn); return () => { subs.delete(fn); }; } };
+
+/** The frame's key in preview.js: its own, so the card that opened it keeps its own state. */
+export const frameKey = (key) => `panel:${key}`;
+/** Show `spec` in the panel; `run`: start it there (a click that moves a running preview). The block shown before stops. */
+export function openPanel(spec, { run = false } = {}) {
+  if (state.open && P()) P().stop(frameKey(state.open.key), "stopped", "");
+  set({ open: { ...spec }, run: run ? state.run + 1 : 0 });
+}
+/** Close the panel: its frame stops first. */
+export function closePanel() {
+  if (state.open && P()) P().stop(frameKey(state.open.key), "stopped", "");
+  if (state.open) set({ open: null, run: 0 });
+}
+/** The card key the panel shows, or null. */
+export const shownKey = () => (state.open ? state.open.key : null);
+
+/** The text of a block's <title>, or "" — what says two blocks are versions of one thing. */
+export function htmlTitle(code) {
+  const m = /<title[^>]*>([\s\S]*?)<\/title>/i.exec(String(code || ""));
+  return m ? m[1].replace(/\s+/g, " ").trim() : "";
+}
+
+/**
+ * A newer version of the shown block: the last complete ```html block in an agent reply after the one it came from.
+ * When the shown block has a <title>, only a block with the same title counts (another page is not a new version);
+ * without one, the newest block does. `msgs` in order; `keyOf` makes a message's key.
+ */
+export function newerVersion(open, msgs, keyOf) {
+  if (!open || !Array.isArray(msgs)) return null;
+  const at = msgs.findIndex(x => keyOf(x) === open.msgKey);
+  if (at < 0) return null;
+  // An attached file: a later agent reply attaching a file of the same name is its newer version. Its HTML is read
+  // when the person picks it (code: null here), as on a card.
+  if (open.att) {
+    const name = String(open.att.name || "").trim().toLowerCase();
+    for (let i = msgs.length - 1; i > at; i--) {
+      const x = msgs[i];
+      if (x.role !== "agent" || !Array.isArray(x.attachments)) continue;
+      for (let k = x.attachments.length - 1; k >= 0; k--) {
+        const a = x.attachments[k];
+        if (!R().isHtmlAttachment(a) || a.name.trim().toLowerCase() !== name) continue;
+        const msgKey = keyOf(x);
+        return { key: `${msgKey}:a${a.id}`, instance: open.instance, msgKey, att: { id: a.id, name: a.name, size: a.size }, code: null, sender: x.sender, ts: x.ts };
+      }
+    }
+    return null;
+  }
+  const title = htmlTitle(open.code);
+  for (let i = msgs.length - 1; i > at; i--) {
+    const x = msgs[i];
+    if (x.role !== "agent") continue;
+    const fences = R().htmlFences(x.text);
+    for (let n = fences.length - 1; n >= 0; n--) {
+      const f = fences[n];
+      if (!f.terminated || (title && htmlTitle(f.code) !== title)) continue;
+      const msgKey = keyOf(x);
+      return { key: `${msgKey}:f${n}`, instance: open.instance, msgKey, n, code: f.code, sender: x.sender, ts: x.ts };
+    }
+  }
+  return null;
+}
+
+// ── The panel's width: this device's choice (a convenience — the panel works without storage) ──
+
+const WIDTH_KEY = "agend_preview_panel_w";
+export const MIN_PANEL = 320, MIN_THREAD = 360, STEP = 32;
+function storedWidth() { try { const v = Number(localStorage.getItem(WIDTH_KEY)); return Number.isFinite(v) && v > 0 ? v : null; } catch { return null; } }
+function storeWidth(w) { try { localStorage.setItem(WIDTH_KEY, String(Math.round(w))); } catch { /* this page only */ } }
+/** The width a panel may have in a split `total` px wide: at least MIN_PANEL, leaving the thread MIN_THREAD. */
+export function clampWidth(w, total) {
+  const max = Math.max(MIN_PANEL, total - MIN_THREAD - 8);
+  return Math.round(Math.min(max, Math.max(MIN_PANEL, w)));
+}
+
+const timeOf = (ts) => (ts ? new Date(ts).toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" }) : "");
+
+/**
+ * The panel, inside the chat's split (`split`: that element — the divider sets its width there, through CSSOM).
+ * props: name (the instance), msgs() → its messages, subscribe(fn) → unsubscribe (the chat store's), keyOf(x),
+ * reveal(msgKey) (the thread shows that message), download(code).
+ */
+export function PreviewPanel({ name, split, msgs, subscribe, keyOf, reveal, download }) {
+  const [st, setSt] = useState(state);
+  const [view, setView] = useState("preview");
+  const [run, setRun] = useState({ state: "idle", reason: "" });
+  const [newer, setNewer] = useState(null);
+  const [newerNote, setNewerNote] = useState("");
+  const reading = useRef(null);   // the newer version whose file is being read (one at a time)
+  const holder = useRef(null), divider = useRef(null), panel = useRef(null);
+  const open = st.open && st.open.instance === name ? st.open : null;
+
+  useEffect(() => panelStore.subscribe(setSt), []);
+  // This device's choice (here or in another tab) decides whether Preview is offered: re-read it when it changes.
+  const [, choice] = useState(0);
+  useEffect(() => (P() ? P().onChange(() => choice(n => n + 1)) : undefined), []);
+  // Leaving the chat (another instance, another panel) closes the panel: its frame stops with the thread's.
+  useEffect(() => () => closePanel(), []);
+
+  const ui = { state: (s, reason) => setRun({ state: s === "starting" || s === "running" ? s : "idle", reason: reason || "" }) };
+  const start = () => {
+    if (!open || !holder.current) return;
+    setView("preview");
+    P().start(frameKey(open.key), holder.current, open.code, ui, { fill: true });
+  };
+  const stop = () => { if (open) P().stop(frameKey(open.key), "stopped", ""); };
+  // A new block in the panel: what ran before is gone (openPanel stopped it); a moved run starts here.
+  useEffect(() => {
+    setRun({ state: "idle", reason: "" });
+    setView("preview");
+    if (open && st.run) start();
+    // Focus goes to the panel's close control that is on screen (Back on a phone, × beside the thread).
+    if (panel.current) { const f = [...panel.current.querySelectorAll(".pv-panel-close")].find(b => b.offsetParent !== null); if (f) f.focus(); }
+  }, [open && open.key, st.run]);
+  // A later reply with a newer version of this block: offered, not swapped in.
+  useEffect(() => {
+    setNewerNote(""); reading.current = null;
+    if (!open) { setNewer(null); return undefined; }
+    const check = () => setNewer(newerVersion(open, msgs() || [], keyOf));
+    check();
+    return subscribe((instance, kind) => { if (instance === name && kind === "msgs") check(); });
+  }, [open && open.key, name]);
+
+  // The divider: drag, or the arrow keys, Home and End; the width is this device's.
+  const widthNow = useRef(MIN_PANEL);
+  const applyWidth = (w, save) => {
+    const sp = split.current; if (!sp) return;
+    const total = sp.clientWidth || 0;
+    const v = clampWidth(w, total);
+    widthNow.current = v;
+    sp.style.setProperty("--pv-w", `${v}px`);           // CSSOM: the page's CSP allows no style attribute
+    if (divider.current) { divider.current.setAttribute("aria-valuenow", String(v)); divider.current.setAttribute("aria-valuemax", String(clampWidth(Infinity, total))); }
+    if (save) storeWidth(v);
+  };
+  useEffect(() => { if (open) applyWidth(storedWidth() ?? (split.current && split.current.clientWidth || 0) / 2, false); }, [!!open]);
+  const width = () => widthNow.current;
+  const setWidth = (w) => applyWidth(w, true);
+  const onKey = (e) => {
+    const k = e.key;
+    if (k === "ArrowLeft") setWidth(width() + STEP);
+    else if (k === "ArrowRight") setWidth(width() - STEP);
+    else if (k === "Home") setWidth(Infinity);
+    else if (k === "End") setWidth(0);
+    else return;
+    e.preventDefault();
+  };
+  const onDown = (e) => {
+    const sp = split.current; if (!sp || e.button !== 0) return;
+    e.preventDefault();
+    const el = e.currentTarget;
+    try { el.setPointerCapture(e.pointerId); } catch { /* the move still works while over the divider */ }
+    sp.classList.add("resizing");         // frames take no pointer events meanwhile, or the drag would stop over one
+    const right = sp.getBoundingClientRect().right;
+    const move = (ev) => applyWidth(right - ev.clientX - 4, false);
+    const up = () => { sp.classList.remove("resizing"); storeWidth(widthNow.current); el.removeEventListener("pointermove", move); el.removeEventListener("pointerup", up); el.removeEventListener("pointercancel", up); };
+    el.addEventListener("pointermove", move);
+    el.addEventListener("pointerup", up);
+    el.addEventListener("pointercancel", up);
+  };
+  // Show the newer version: an attached file's HTML is read first. A read the panel moved on from is dropped.
+  const showNewer = async () => {
+    if (!newer || reading.current) return;
+    if (newer.code != null) { openPanel(newer); return; }
+    const was = open && open.key, mine = reading.current = newer;
+    setNewerNote(t("chat.pvLoading"));
+    const r = await loadHtmlAttachment(newer.att);
+    if (reading.current !== mine) return;
+    reading.current = null;
+    const now = panelStore.get().open;
+    if (!now || now.key !== was) return;
+    if (!r.ok) { setNewerNote(t(r.reason === "over" ? "chat.pvAttOver" : r.reason === "gone" ? "chat.pvAttGone" : "chat.pvAttFailed")); return; }
+    openPanel({ ...newer, code: r.code });
+  };
+  const fileName = open && open.att ? open.att.name : undefined;
+  // Esc in the panel closes it (and is not the chat's "stop the reply").
+  const onPanelKey = (e) => { if (e.key === "Escape" && !e.isComposing) { e.preventDefault(); closePanel(); } };
+
+  if (!open) return null;
+  const going = run.state === "starting" || run.state === "running";
+  const a = P().availability();
+  const note = run.reason || (going ? (run.state === "starting" ? t("chat.pvStarting") : "") : a.ok ? t("chat.pvPanelIdle") : a.reason);
+  const source = t("chat.pvSource", open.sender || name, timeOf(open.ts));
+  return html`<div class="pv-divider" ref=${divider} role="separator" aria-orientation="vertical" tabindex="0" aria-label=${t("chat.pvResize")}
+      aria-valuemin=${String(MIN_PANEL)} onKeyDown=${onKey} onPointerDown=${onDown}></div>
+    <aside class="pv-panel" ref=${panel} aria-label=${t("chat.pvPanel")} onKeyDown=${onPanelKey}>
+      <div class="pv-panel-head">
+        <button type="button" class="icon-btn only-narrow pv-panel-close" title=${t("chat.pvBack")} aria-label=${t("chat.pvBack")} onClick=${closePanel}><${Icon} name="back" size=${18} /></button>
+        <div class="pv-panel-title"><strong>${t("chat.pvPanel")}</strong>
+          <button type="button" class="pv-source" title=${source} onClick=${() => { if (window.matchMedia && window.matchMedia("(max-width: 899px)").matches) closePanel(); reveal(open.msgKey); }}>${source}</button></div>
+        <button type="button" class="icon-btn only-wide pv-panel-close" title=${t("chat.pvClose")} aria-label=${t("chat.pvClose")} onClick=${closePanel}><${Icon} name="close" size=${18} /></button>
+      </div>
+      <div class="pv-panel-bar">
+        <div class="seg-inline" role="group" aria-label=${t("chat.pvPanel")}>
+          <button type="button" class=${`btn btn-sm${view === "preview" ? " on" : ""}`} aria-pressed=${view === "preview" ? "true" : "false"} onClick=${() => setView("preview")}><${Icon} name="eye" size=${14} />${t("chat.pvPage")}</button>
+          <button type="button" class=${`btn btn-sm${view === "code" ? " on" : ""}`} aria-pressed=${view === "code" ? "true" : "false"} onClick=${() => setView("code")}><${Icon} name="code" size=${14} />${t("chat.pvCode")}</button>
+        </div>
+        <span class="grow"></span>
+        ${going ? html`<button type="button" class="btn btn-sm pv-panel-reload" title=${t("chat.pvReload")} onClick=${() => { stop(); start(); }}><${Icon} name="restart" size=${14} /><span class="lbl">${t("chat.pvReload")}</span></button>
+          <button type="button" class="btn btn-sm pv-panel-stop" title=${t("chat.pvStop")} onClick=${stop}><${Icon} name="stop" size=${14} /><span class="lbl">${t("chat.pvStop")}</span></button>`
+          : html`<button type="button" class="btn btn-sm btn-primary pv-panel-run" title=${t("chat.pvPreview")} disabled=${!a.ok} onClick=${start}><${Icon} name="play" size=${14} /><span class="lbl">${t("chat.pvPreview")}</span></button>`}
+        <button type="button" class="btn btn-sm pv-panel-dl" title=${t("chat.pvDownload")} onClick=${() => download(open.code, fileName)}><${Icon} name="download" size=${14} /><span class="lbl">${t("chat.pvDownload")}</span></button>
+      </div>
+      ${newer && newer.key !== open.key ? html`<div class="pv-newer" role="status"><span>${t("chat.pvNewer", timeOf(newer.ts))}</span>
+        <button type="button" class="btn btn-sm pv-newer-show" onClick=${showNewer}>${t("chat.pvNewerShow")}</button>${newerNote ? html`<span class="pv-newer-note">${newerNote}</span>` : null}</div>` : null}
+      ${going ? html`<div class="pv-banner">${P().BANNER}</div>` : null}
+      ${note && view === "preview" ? html`<div class="pv-note">${note}</div>` : null}
+      <div class=${`pv-panel-body${view === "code" ? " show-code" : ""}`}>
+        <div class="pv-holder" ref=${holder}></div>
+        ${view === "code" ? html`<pre class="pv-code"><code>${open.code}</code></pre>` : null}
+      </div>
+    </aside>`;
+}

package/dist/ui/preview.js

@@ -128,8 +128,10 @@
   /**
    * Run `html` in `holder` (a node of the card) for `key`. `ui` is told what happened: ui.state(name, reason) with
    * "starting" | "running" | "stopped" | "unavailable". One preview at a time: any other running one stops first.
+   * opts.fill (#1481, the side panel): the frame fills its holder — the same frame from mountPreview, only sized by the
+   * panel instead of by the frame's height messages, which it then ignores.
    */
-  function start(key, holder, html, ui) {
+  function start(key, holder, html, ui, opts) {
     var a = availability();
     if (!a.ok) { ui.state("unavailable", a.reason); return false; }
     if (typeof html !== "string" || utf8Bytes(html) > LIMITS.maxBytes) { ui.state("unavailable", "This HTML is over 1 MiB; it is not previewed."); return false; }
@@ -139,14 +141,15 @@
     var card = {
       key: key, iframe: iframe, ch: randomCh(), holder: holder, html: html, ui: ui, rendered: false,
       height: LIMITS.minHeight, lastApplied: -Infinity, appliedInSecond: [], frozen: false, growth: [], pendingFrame: false,
-      readyTimer: null, watchdogTimer: null,
+      readyTimer: null, watchdogTimer: null, fill: !!(opts && opts.fill),
     };
+    if (card.fill) iframe.classList.add("fill");
     live.set(key, card);
     card.readyTimer = root.setTimeout(function () {
       if (live.get(key) === card && !card.rendered) stop(key, "unavailable", "Preview unavailable: the preview did not answer within 3 s. If an earlier preview froze, it may still be running — open the dashboard in a new tab. Over SSH, forward the preview port too.");
     }, LIMITS.readyMs);
     holder.appendChild(iframe);
-    setHeight(card, LIMITS.minHeight);
+    if (!card.fill) setHeight(card, LIMITS.minHeight);
     ui.state("starting", "");
     return true;
   }
@@ -235,6 +238,7 @@
   /** Height rules (design §4.2): clamp to [40, 4000]; ≤ 1 per animation frame and ≤ 10 per second; Δ < 2 px ignored;
    *  after 5 consecutive increases within 2 s the height freezes and the frame scrolls. */
   function requestHeight(card, h) {
+    if (card.fill) return;                            // the panel sizes it (#1481)
     var want = Math.max(LIMITS.minHeight, Math.min(LIMITS.maxHeight, h));
     if (Math.abs(want - card.height) < LIMITS.minDelta) return;
     var t = now();

package/dist/ui/settings-apply.js

@@ -26,7 +26,7 @@ function view() {
   if (!op) return null;
   return {
     id: op.id, phase: op.phase, error: op.error, job: op.job, lostJob: op.lostJob, restart: op.restart,
-    steps: op.steps.map(({ label, impact, status, error, pendingId }) => ({ label, impact, status, error: error || null, pendingId: pendingId || null })),
+    steps: op.steps.map(({ label, impact, status, error, pendingId, note }) => ({ label, impact, status, error: error || null, pendingId: pendingId || null, ...(note ? { note } : {}) })),
     leftover: op.leftover,
   };
 }
@@ -138,6 +138,8 @@ async function rotateConnectionSecret(step, o) {
     if (status && status.ok) result = status.body || result;
   }
   const ok = result.result === "applied" || result.result === "restart_required";
+  // Stored, but no adapter was running to take it (#1519 P1): said as such — not "done", and never "failed".
+  if (result.result === "restart_required") { step.note = t("settings.tokenSavedRestart"); publish(); }
   return { ok, status: ok ? 200 : 409, body: ok ? result : { error: result.error || result.result || "apply failed" } };
 }
 

package/dist/ui/settings-dialogs.js

@@ -10,6 +10,9 @@ import { Icon } from "/assets/ui-icons.js";
 import { toast } from "/assets/ui-toast.js";
 import { confirmDialog } from "/assets/ui-confirm.js";
 import { api, confirmedWrite, newKey } from "./settings-confirm.js";
+import { botHandle, TokenEnvNote, TokenField, verifyBotToken } from "./settings-token.js";
+import { DiscordServerPicker } from "./settings-discord.js";
+import { startOperation } from "./settings-apply.js";
 import {
   ACCESS_MODES, AGENT_FIELDS, AGENT_MODES, BOT_FIELDS, CH_TYPES, CLASSIC_FIELDS, LOG_LEVELS, TOOL_PROGRESS, TOOL_SETS,
   VISIBILITY_MODES, accessConfirmations, agentForm, agentPatch, backendOptions, changedFields, channelId, channelsOf,
@@ -341,15 +344,31 @@ export function BotDialog({ id, ctx, onClose }) {
   const [bindBusy, setBindBusy] = useState(false);
   const [token, setToken] = useState("");
   const [tokenNote, setTokenNote] = useState(null);
+  // Replace token (#1519 P1): the field opens on Replace, and a token is staged only once the platform has named its bot.
+  const [replacing, setReplacing] = useState(false);
+  const [tokenId, setTokenId] = useState(null);
+  const [tokenBusy, setTokenBusy] = useState(false);
+  const status = (ctx.connections || []).find((c) => c && c.id === id) || {};
   const [emojis, setEmojis] = useState({ value: null, baseline: null });
   const lease = useLease("bot-dialog");
   const accessWarn = mode === "locked" && users.length === 0 ? "accessLockedEmpty" : "";
+  // The token's revision (#1529 review): typing moves it, and a Verify for an older value is dropped when it lands.
+  const tokenRev = useRef(0);
+  const verifyToken = async () => {
+    setTokenBusy(true);
+    const mine = epoch.current, at = tokenRev.current;
+    const identity = await verifyBotToken(type, token);
+    if (!lease.current() || epoch.current !== mine) return;
+    setTokenBusy(false);
+    if (tokenRev.current === at) setTokenId(identity);
+  };
   const stageToken = () => {
     if (!ch) return;
     if (!token) { setTokenNote({ error: tn("tokenRequired") }); return; }
+    if (!tokenId || !tokenId.valid) { setTokenNote({ error: tn("wizardNeedVerify") }); return; }
     // The token goes into the staged change and nowhere else: not a label, not the URL, not storage.
     ctx.stage(`secret:${id}`, { label: tn("rotateToken", type), impact: schema.order[0], connectionSecret: { id, secret: token } });
-    setToken("");
+    setToken(""); setTokenId(null); setReplacing(false);
     setTokenNote({ text: tn("tokenQueued") });
   };
   const stage = () => {
@@ -419,45 +438,96 @@ export function BotDialog({ id, ctx, onClose }) {
         previewBody=${(map) => ({ channel_id: id, platform: type, channel_config: map })} onChange=${setEmojis} />
     </${Drawer}>
     <${Drawer} title=${tn("advancedSection")}>
-      <div class="field"><span>${tn("tokenEnv")}</span><code>${ch.bot_token_env || tn("noTokenEnv")}</code></div>
-      <div class="field"><label for="bot-token">${tn("tokenField")}</label>
-        <input id="bot-token" type="password" autocomplete="new-password" value=${token} placeholder=${tn("tokenPlaceholder")} onInput=${(e) => setToken(e.target.value)} />
-        <p class="note">${tn("tokenHint")}</p>
-        <div class="dlg-inline-actions"><button type="button" class="btn btn-sm" onClick=${stageToken}>${tn("tokenButton")}</button>
-          ${tokenNote ? html`<span class=${`feedback${tokenNote.error ? " error" : ""}`} role="status">${tokenNote.error || tokenNote.text}</span>` : null}</div></div>
+      <div class="field"><span>${tn("tokenStatus")}</span>
+        <div class="dlg-inline-actions"><span class="token-status">${status.token_present === false ? tn("tokenMissing")
+          : status.identity && status.identity.username ? tn("tokenSetAs", botHandle(status.identity.username)) : tn("tokenSet")}</span>
+          ${replacing ? null : html`<button type="button" class="btn btn-sm" onClick=${() => { setReplacing(true); setTokenNote(null); }}>${tn("tokenReplace")}</button>`}</div></div>
+      ${replacing ? html`<${TokenField} id="bot-token" platform=${type} value=${token} identity=${tokenId} busy=${tokenBusy}
+          onInput=${(v) => { tokenRev.current++; setToken(v); setTokenId(null); }} onVerify=${verifyToken} hint=${tn("tokenHint")} />
+        <div class="dlg-inline-actions"><button type="button" class="btn btn-sm" disabled=${!tokenId || !tokenId.valid} onClick=${stageToken}>${tn("tokenButton")}</button>
+          <button type="button" class="btn btn-sm btn-ghost" onClick=${() => { tokenRev.current++; setReplacing(false); setToken(""); setTokenId(null); }}>${tn("cancel")}</button></div>` : null}
+      ${tokenNote ? html`<p class=${`feedback${tokenNote.error ? " error" : ""}`} role="status">${tokenNote.error || tokenNote.text}</p>` : null}
+      <${TokenEnvNote} name=${ch.bot_token_env} />
       <div class="dlg-inline-actions"><button type="button" class="btn btn-sm danger" onClick=${remove}><${Icon} name="trash" size=${14} />${tn("deleteBot")}</button></div>
     </${Drawer}>
   </${EditDialog}>`;
 }
 
-/** A new connection: written at once (as before), through the confirmation an admin may have to give. */
+/**
+ * A new connection (#1519 P1): the bot token, checked with the platform, then the server-side plan — a free id and a
+ * generated token env (shown under Advanced, read-only) — then the same write the setup wizard makes, without an agent:
+ * one operation (the confirmation an admin may have to give, then Apply, which offers the restart a new connection
+ * needs). Never a replacement: the server refuses an id or token env another connection holds.
+ */
 export function NewBotDialog({ ctx, onClose }) {
   const lease = useLease("new-bot");
-  const [f, setF] = useState({ type: "discord", id: "", env: "", group: "" });
+  const [f, setF] = useState({ type: "discord", id: "", token: "", identity: null, guilds: [], group: "", general: "" });
+  const [plan, setPlan] = useState(null);
   const [busy, setBusy] = useState(false);
   const [err, setErr] = useState("");
+  // The form's revision (#1529 review): any change to the token, platform, id or group moves it; a Verify or a plan
+  // that began before is dropped when it lands — never restoring an old token, naming it, or planning for it.
+  const rev = useRef(0);
+  const body = (x) => ({ platform: x.type, connection_only: true, ...(x.id.trim() ? { channel_id: x.id.trim() } : {}),
+    ...(x.group.trim() ? (x.type === "discord" ? { guild_id: x.group.trim() } : { group_id: x.group.trim() }) : {}),
+    ...(x.type === "discord" && x.general.trim() ? { general_channel_id: x.general.trim() } : {}) });
+  const planFor = async (x) => {
+    const at = rev.current;
+    const res = await api("/api/settings/quickstart/plan", { method: "POST", body: JSON.stringify(body(x)) }).catch(() => ({ ok: false, body: {} }));
+    if (!lease.current() || rev.current !== at) return null;
+    if (!res.ok) { setErr((res.body && res.body.error) || tn("failed")); setPlan(null); return null; }
+    setErr(""); setPlan(res.body); return res.body;
+  };
+  const verify = async () => {
+    const at = rev.current, x = f;
+    const live = () => lease.current() && rev.current === at;
+    setBusy(true); setErr("");
+    const identity = await verifyBotToken(x.type, x.token);
+    if (!live()) { if (lease.current()) setBusy(false); return; }
+    let guilds = [];
+    if (identity.valid && x.type === "discord") {
+      const g = await api("/api/settings/quickstart/probe", { method: "POST", body: JSON.stringify({ action: "guilds", token: x.token }) }).catch(() => null);
+      if (!live()) { if (lease.current()) setBusy(false); return; }
+      guilds = (g && g.body && g.body.guilds) || [];
+    }
+    // Onto the form as it is now (same revision, so the same token): never a copy of the form from before the await.
+    setF((cur) => ({ ...cur, identity, guilds })); setBusy(false);
+    if (identity.valid) await planFor({ ...x, identity, guilds });
+  };
   const save = async () => {
-    if (!f.env.trim()) { setErr(tn("tokenEnvRequired")); return; }
-    const next = [...channelsOf(ctx.fleet), { id: f.id.trim() || undefined, type: f.type, bot_token_env: f.env.trim(), group_id: f.group.trim() || undefined, access: { mode: "locked", allowed_users: [] } }];
+    if (!f.identity || !f.identity.valid) { setErr(tn("wizardNeedVerify")); return; }
+    const x = f;
     setBusy(true);
-    const res = await confirmedWrite("/api/settings/fleet/channels", { method: "PUT", body: next, label: tn("addBotLabel", f.id.trim() || f.type) }).catch(() => ({ ok: false, body: {} }));
-    if (!res.ok) { toast((res.body && res.body.error) || tn("failed"), false); if (lease.current()) setBusy(false); return; }
-    toast(tn("saved"));
-    ctx.reload();
-    if (lease.current()) onClose();
+    const p = await planFor(x);
+    if (!p) { if (lease.current()) setBusy(false); return; }
+    const handed = startOperation([{ label: tn("addBotLabel", p.channel_id), impact: impactOf(ctx.schema, "fleet.channels"),
+      request: { method: "POST", url: "/api/settings/quickstart/commit",
+        body: { ...body(x), channel_id: p.channel_id, token_env: p.token_env, token_env_generated: true, token: x.token }, sensitive: true } }]);
+    if (!handed) { setErr(tn("applyBusyLocal")); setBusy(false); return; }
+    setF((x) => ({ ...x, token: "" }));
+    onClose();
   };
-  const set = (k) => (e) => setF({ ...f, [k]: e.target.value });
+  // A change of platform or id is another connection: what was verified and planned no longer applies. The server or
+  // group does not change the id or the token's name, so the plan (and its name under Advanced) stays.
+  const set = (k) => (v) => { rev.current++; setF((x) => ({ ...x, [k]: v, ...(k === "type" ? { identity: null, guilds: [], group: "", general: "" } : {}) })); if (k !== "group" && k !== "general") setPlan(null); };
   return html`<${Dialog} title=${tn("newBot")} onClose=${onClose} busy=${busy}
     actions=${html`<button type="button" class="btn" disabled=${busy} onClick=${onClose}>${tn("cancel")}</button>
-      <button type="button" class="btn btn-primary" disabled=${busy} onClick=${save}>${tn("save")}</button>`}>
+      <button type="button" class="btn btn-primary" disabled=${busy || !f.identity || !f.identity.valid} onClick=${save}>${tn("save")}</button>`}>
     <div class="form">
-      <div class="grid2">
-        <div class="field"><label for="nb-type">${tn("type")}</label><${Select} id="nb-type" value=${f.type} onChange=${(v) => setF({ ...f, type: v })} options=${CH_TYPES} /></div>
-        <div class="field"><label for="nb-id">${tn("adapterId")}</label><input id="nb-id" type="text" placeholder="persona1" value=${f.id} onInput=${set("id")} /></div>
-        <div class="field"><label for="nb-env">${tn("tokenEnv")} *</label><input id="nb-env" type="text" placeholder="BOT_TOKEN_ENV" value=${f.env} onInput=${set("env")} /></div>
-        <div class="field"><label for="nb-group">${tn("groupId")}</label><input id="nb-group" type="text" value=${f.group} onInput=${set("group")} /></div>
-      </div>
-      <p class="note">${tn("envHint")}</p>
+      <div class="field"><label for="nb-type">${tn("type")}</label><${Select} id="nb-type" value=${f.type} onChange=${set("type")} options=${CH_TYPES} /></div>
+      <${TokenField} id="nb-token" platform=${f.type} value=${f.token} identity=${f.identity} busy=${busy}
+        onInput=${(v) => { rev.current++; setF((x) => ({ ...x, token: v, identity: null, guilds: [] })); setPlan(null); }} onVerify=${verify} hint=${tn("newBotTokenHint")} />
+      ${f.type === "discord"
+        ? html`<${DiscordServerPicker} idPrefix="nb" token=${f.identity && f.identity.valid ? f.token : ""} bot=${f.identity && botHandle(f.identity.username)}
+            invite=${f.identity && f.identity.invite} portal=${f.identity && f.identity.portal} guilds=${f.guilds} onGuilds=${(g) => setF((x) => ({ ...x, guilds: g }))}
+            guild=${f.group} onGuild=${set("group")} channel=${f.general} onChannel=${set("general")} />`
+        : html`<div class="field"><label for="nb-group">${tn("groupIdField")}</label>
+            <input id="nb-group" type="text" value=${f.group} onInput=${(e) => set("group")(e.target.value.trim())} /></div>`}
+      <${Drawer} title=${tn("advancedSection")}>
+        <div class="field"><label for="nb-id">${tn("connectionIdOptional")}</label><input id="nb-id" type="text" placeholder=${plan ? plan.channel_id : f.type}
+          value=${f.id} onInput=${(e) => set("id")(e.target.value)} onBlur=${() => { if (f.identity && f.identity.valid) planFor(f); }} /></div>
+        <${TokenEnvNote} name=${plan && plan.token_env} />
+      </${Drawer}>
       ${err ? html`<p class="feedback error" role="alert">${err}</p>` : null}
     </div></${Dialog}>`;
 }

package/dist/ui/settings-discord.js

@@ -0,0 +1,130 @@
+// #1519 P3 (docs/design/ux-onboarding-walkthrough.md §5.3): after a Discord token verifies — the invite (one permission
+// set, never Administrator), the Message Content note with the portal's Bot page, the server the bot joins found by
+// asking Discord every 2 s for up to 2 minutes, and the server's text channels as a list ("general" first choice). The
+// setup wizard and New connection use it.
+//
+// Every read is an operation of its own (#1533 review): numbered when it starts, and its answer is taken only while it is
+// still the current one of its kind and this picker is still on the page. A new token, another server, a manual choice,
+// Stop, the 2-minute limit or leaving the page each retire what was asked before — an answer about A never lands after
+// B, nor after A again (an older A), nor once the page is gone.
+import { html, useEffect, useRef, useState } from "/assets/app-html.js";
+import { t } from "/assets/app-i18n.js";
+import { api } from "./settings-confirm.js";
+import { Select } from "./settings-dialogs.js";
+
+const tn = (k, ...v) => t(`settings.${k}`, ...v);
+export const POLL_MS = 2000, POLL_FOR_MS = 120_000;
+const clock = () => (typeof performance !== "undefined" ? performance.now() : Date.now());   // elapsed time: monotonic
+const probe = (body) => api("/api/settings/quickstart/probe", { method: "POST", body: JSON.stringify(body) }).catch(() => ({ ok: false, body: {} }));
+
+/**
+ * props: idPrefix, token, bot (@name), invite, portal, guilds, onGuilds(list), guild, onGuild(id), channel, onChannel(id).
+ * The parent owns the values; this owns the asking.
+ */
+export function DiscordServerPicker({ idPrefix, token, bot, invite, portal, guilds, onGuilds, guild, onGuild, channel, onChannel }) {
+  const [polling, setPolling] = useState(null);            // { timedOut } while waiting for the bot to join
+  const [channels, setChannels] = useState(null);          // null: not asked; { list } | { error }
+  const live = useRef(true);
+  const now = useRef({ token, guild, channel });
+  now.current = { token, guild, channel };
+  // The current operation of each kind; an answer is taken only while its number is still the one here.
+  // `choice`: the one generation of the server choice that polls and Check again both write (#1533 review r2) — a read
+  // started before any later pick, Check again or Stop cannot pick.
+  const op = useRef({ poll: 0, check: 0, channels: 0, choice: 0 });
+  const poll = useRef({ timer: null, until: 0, known: new Set(), asking: false });
+  const chosen = useRef(false);                            // the person picked a General channel since this server's list was asked
+
+  const stopPolling = (timedOut = false) => {
+    op.current.poll++; op.current.choice++;                // retires the poll's reads still on their way
+    if (poll.current.timer) { clearInterval(poll.current.timer); poll.current.timer = null; }
+    setPolling(timedOut ? { timedOut: true } : null);
+  };
+  useEffect(() => () => { live.current = false; if (poll.current.timer) clearInterval(poll.current.timer); }, []);
+  // A new token is another bot: what was being waited for, or listed, was about the old one — and so was its General.
+  const lastToken = useRef(token);
+  useEffect(() => {
+    op.current.check++; op.current.channels++; stopPolling(); setChannels(null);
+    if (lastToken.current !== token && now.current.channel) onChannel("");
+    lastToken.current = token;
+  }, [token]);
+
+  /** One read of the bot's servers, for operation `kind` number `seq`; joined: pick it (unless the person chose meanwhile). */
+  const readGuilds = async (kind, seq, known, deadline) => {
+    const asked = token, choice = op.current.choice;
+    const res = await probe({ action: "guilds", token: asked });
+    const current = () => live.current && op.current[kind] === seq && op.current.choice === choice && now.current.token === asked
+      && (deadline == null || clock() <= deadline);
+    if (!current()) return false;
+    const list = (res.ok && res.body && Array.isArray(res.body.guilds)) ? res.body.guilds : null;
+    if (!list) return false;
+    onGuilds(list);
+    const joined = list.filter((g) => !known.has(g.id));
+    if (!joined.length) return false;
+    if (joined.length === 1 || !now.current.guild) pickGuild(joined[0].id, false);
+    return true;
+  };
+  const startPolling = () => {
+    stopPolling();
+    const seq = op.current.poll, known = new Set((guilds || []).map((g) => g.id)), until = clock() + POLL_FOR_MS;
+    poll.current = { timer: null, until, known, asking: false };
+    setPolling({ timedOut: false });
+    const record = poll.current;
+    record.timer = setInterval(async () => {
+      if (op.current.poll !== seq) return;
+      if (clock() > until) { stopPolling(true); return; }
+      if (record.asking) return;                           // one read at a time
+      record.asking = true;
+      // Its own record only: a later poll's in-flight flag is not this read's to clear.
+      await readGuilds("poll", seq, known, until).finally(() => { record.asking = false; });
+    }, POLL_MS);
+  };
+  // Check again: a new, explicit read of its own (it does not revive a stopped poll).
+  // A newer, explicit read: it supersedes any read still on its way (theirs no longer picks).
+  const checkAgain = () => { op.current.choice++; const seq = ++op.current.check; void readGuilds("check", seq, poll.current.known, null); };
+
+  /** A server is picked — by the person (`manual`) or because the bot joined it. Either way the old General goes. */
+  const pickGuild = (id, manual) => {
+    // Any pick — the person's, or a read's — ends the waiting and retires every other read still on its way.
+    stopPolling(); op.current.check++;
+    if (id !== now.current.guild && now.current.channel) onChannel("");
+    onGuild(id);
+  };
+  const pickChannel = (id) => { chosen.current = true; onChannel(id); };
+
+  // The chosen server's text channels; "general" when there is one and none is chosen yet.
+  useEffect(() => {
+    const seq = ++op.current.channels;
+    chosen.current = false;
+    setChannels(null);
+    if (!guild || !token) return;
+    const askedToken = token, askedGuild = guild;
+    (async () => {
+      const res = await probe({ action: "channels", token: askedToken, guild_id: askedGuild });
+      if (!live.current || op.current.channels !== seq || now.current.token !== askedToken || now.current.guild !== askedGuild) return;
+      if (!res.ok || !res.body || !Array.isArray(res.body.channels)) { setChannels({ error: (res.body && res.body.error) || tn("failed") }); return; }
+      setChannels({ list: res.body.channels });
+      // The first choice only fills an empty choice the person has not made.
+      if (!chosen.current && !now.current.channel) {
+        const general = res.body.channels.find((c) => c.name.toLowerCase() === "general");
+        if (general) onChannel(general.id);
+      }
+    })();
+  }, [guild, token]);
+
+  return html`<div class="discord-setup">
+    ${invite ? html`<div class="dlg-inline-actions">
+      <a class="btn btn-sm btn-primary" href=${invite} target="_blank" rel="noopener noreferrer" onClick=${startPolling}>${tn("discordInvite", bot || tn("discordTheBot"))}</a>
+      ${polling && !polling.timedOut ? html`<span class="note" role="status">${tn("discordWaitingJoin")}</span>` : null}
+      ${polling ? html`<button type="button" class="btn btn-sm btn-ghost" onClick=${checkAgain}>${tn("discordCheckAgain")}</button>` : null}</div>
+      <p class="note">${tn("discordIntentNote")} ${portal ? html`<a href=${portal} target="_blank" rel="noopener noreferrer">${tn("discordPortalBot")}</a>` : null}</p>` : null}
+    <div class="field"><label for=${`${idPrefix}-guild`}>${tn("guildIdField")}</label>
+      ${guilds && guilds.length
+        ? html`<${Select} id=${`${idPrefix}-guild`} value=${guild} onChange=${(v) => pickGuild(v, true)} options=${["", ...guilds.map((g) => ({ value: g.id, label: `${g.name} (${g.id})` }))]} />`
+        : html`<input id=${`${idPrefix}-guild`} type="text" value=${guild} placeholder=${tn("discordNoServerYet")} onInput=${(e) => pickGuild(e.target.value.trim(), true)} />`}</div>
+    <div class="field"><label for=${`${idPrefix}-gen`}>${tn("wizardGeneralChannel")}</label>
+      ${channels && channels.list && channels.list.length
+        ? html`<${Select} id=${`${idPrefix}-gen`} value=${channel} onChange=${pickChannel} options=${["", ...channels.list.map((c) => ({ value: c.id, label: `#${c.name}` }))]} />`
+        : html`<input id=${`${idPrefix}-gen`} type="text" value=${channel} onInput=${(e) => pickChannel(e.target.value.trim())} />`}
+      ${channels && channels.error ? html`<p class="feedback warning">${channels.error}</p>` : null}</div>
+  </div>`;
+}

package/dist/ui/settings-model.js

@@ -275,3 +275,24 @@ export function fullModelRequests(model, current) {
   }
   return out;
 }
+
+/**
+ * #1519 P6 (design §5.6): one connection's own state, from its own metadata (GET /api/settings/connections) — not the
+ * fleet's. { key, cls, bot }: key names the settings string, cls the dot ("ok" | "warn" | "bad" | "off"), bot its @name.
+ * In order: no fleet answering, no token, a named problem, then the adapter's own status.
+ */
+export function connectionState(meta, fleetUp) {
+  const m = meta || {};
+  if (!fleetUp) return { key: "problem", cls: "bad" };
+  if (m.token_present === false) return { key: "connTokenMissing", cls: "bad" };
+  if (m.problem === "missing_intent") return { key: "discordMissingIntent", cls: "bad" };
+  if (m.problem === "rejected") return { key: "connRejected", cls: "bad" };
+  const bot = m.identity && m.identity.username ? `@${String(m.identity.username).replace(/^@/, "")}` : "";
+  switch (m.status) {
+    case "connected": return { key: bot ? "connConnectedAs" : "connected", cls: "ok", bot };
+    case "retrying": return { key: "connReconnecting", cls: "warn" };
+    case "starting": return { key: "connStarting", cls: "warn" };
+    case "failed": return { key: "connFailed", cls: "bad" };
+    default: return { key: "connNotRunning", cls: "off" };
+  }
+}