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

package/dist/ui/chat-thread.js

@@ -8,6 +8,7 @@
 // Unrelated updates (a new message, another message's tick) stop nothing (#1306 §6.2, #1408 §4).
 import "./chat-render.js";
 import "./preview.js";
+import { loadHtmlAttachment } from "./html-attachment.js";
 
 const R = () => globalThis.AgendChatRender;
 const P = () => globalThis.AgendPreview;
@@ -44,7 +45,23 @@ export function createThread(list, scroller, opts) {
     // renderMarkdown escapes the whole text before it adds any tag of its own (chat-render.js).
     const ticks = u && x.delivery ? R().deliveryHtml(x.delivery, TICKS()) : "";
     const tools = u ? "" : `<div class="msg-tools"><button type="button" class="chip-btn icon-only" data-act="copyMsg" data-arg="${escAttr(msgKey(x))}" title="${escAttr(tr("chat.copyMessage"))}" aria-label="${escAttr(tr("chat.copyMessage"))}">${COPY}</button></div>`;
-    return `<div class="msg ${u ? "user" : "agent"}"><div class="meta"><span class="sender">${escAttr(x.sender)}</span><span class="time">${time}</span>${ticks}</div><div class="body"><div class="md">${R().renderMarkdown(x.text, x.role === "agent" ? { htmlCards: true } : undefined)}</div>${R().attachmentsHtml(x.attachments)}</div>${tools}</div>`;
+    const buttons = x.role === "agent" ? replyButtonsHtml(x.buttons) : "";
+    return `<div class="msg ${u ? "user" : "agent"}"><div class="meta"><span class="sender">${escAttr(x.sender)}</span><span class="time">${time}</span>${ticks}</div><div class="body"><div class="md">${R().renderMarkdown(x.text, x.role === "agent" ? { htmlCards: true } : undefined)}</div>${R().attachmentsHtml(x.attachments, x.role === "agent" ? { htmlCards: true } : undefined)}${buttons}</div>${tools}</div>`;
+  }
+  /**
+   * #1266: an agent reply's buttons. Labels are text (escaped, never Markdown); the click names the set and the index,
+   * nothing else. Ended (chosen / expired) or a click in flight: every button off; the chosen one marked, and who.
+   */
+  function replyButtonsHtml(b) {
+    if (!b || typeof b.id !== "string" || !Array.isArray(b.labels) || !b.labels.length) return "";
+    const busy = !!(opts.replyButtonBusy && opts.replyButtonBusy(b.id));
+    const off = b.state !== "open" || busy;
+    const items = b.labels.map((label, i) => {
+      const chosen = b.state === "chosen" && b.chosen === i;
+      return `<button type="button" class="btn btn-sm rb-btn${chosen ? " chosen" : ""}" data-act="replyButton" data-arg="${escAttr(`${b.id}:${i}`)}"${off ? " disabled" : ""}>${escAttr(chosen ? `✓ ${label}` : label)}</button>`;
+    }).join("");
+    const note = b.state === "chosen" ? trf("chat.rbChosen", b.by || "") : b.state === "expired" ? tr("chat.rbExpired") : "";
+    return `<div class="rb-row" role="group" aria-label="${escAttr(tr("chat.rbGroup"))}">${items}${note ? `<span class="rb-note">${escAttr(note)}</span>` : ""}</div>`;
   }
   function msgNode(html, x, stoppedKeys) {
     const tpl = list.ownerDocument.createElement("template");
@@ -76,72 +93,108 @@ export function createThread(list, scroller, opts) {
     }
   }
 
-  // HTML cards (#1306): each ```html fence of a server-marked agent message gets a card under its code block. Building
-  // a card makes no frame; Preview does (AgendPreview.start → mountPreview).
+  // HTML cards (#1306): each ```html fence of a server-marked agent message gets a card under its code block, and each
+  // .html/.htm file it attached gets one under its files (§6.1, Q4). Building a card makes no frame and fetches
+  // nothing; Preview does (AgendPreview.start → mountPreview), after reading an attachment's HTML on that click.
   function decorateHtmlCards(node, x, stoppedKeys) {
     const doc = list.ownerDocument;
     const fences = R().htmlFences(x.text);
     for (const ph of node.querySelectorAll(".html-card[data-card]")) {
       const n = Number(ph.dataset.card), fence = fences[n];
       if (!fence) continue;
-      const key = `${msgKey(x)}:f${n}`;
       ph.textContent = "";
       if (ph.classList.contains("truncated") || !fence.terminated) {
         const note = doc.createElement("div"); note.className = "pv-note"; note.textContent = tr("chat.pvTruncated"); ph.append(note);
         continue;
       }
-      const el = (tag, cls, text) => { const e = doc.createElement(tag); if (cls) e.className = cls; if (text != null) e.textContent = text; return e; };
-      const head = el("div", "pv-head");
-      const label = el("span", "pv-label", tr("chat.pvHtml"));
-      const run = el("button", "btn btn-sm pv-run", tr("chat.pvPreview")); run.type = "button";
-      const stopB = el("button", "btn btn-sm pv-stop", tr("chat.pvStop")); stopB.type = "button"; stopB.hidden = true;
-      const dl = el("button", "btn btn-sm btn-ghost pv-dl", tr("chat.pvDownload")); dl.type = "button";
-      const panel = opts.panel || null;
-      const toPanel = panel ? el("button", "btn btn-sm btn-ghost pv-open", tr("chat.pvOpenPanel")) : null;
-      if (toPanel) toPanel.type = "button";
-      const menu = el("details", "pv-menu");
-      const sum = el("summary", null, "⋯"); sum.title = tr("chat.pvMenu"); sum.setAttribute("aria-label", tr("chat.pvMenu"));
-      const optB = el("button", "chip-btn pv-opt"); optB.type = "button";
-      const neverB = el("button", "chip-btn pv-never"); neverB.type = "button";
-      menu.append(sum, optB, neverB);
-      head.append(label, run, stopB, ...(toPanel ? [toPanel] : []), dl, menu);
-      const note = el("div", "pv-note");
-      const banner = el("div", "pv-banner", P().BANNER); banner.hidden = true;
-      const holder = el("div", "pv-holder");
-      ph.append(head, note, banner, holder);
-      let state = "idle";
-      const refresh = (reason) => {
-        const a = P().availability();
-        const going = state === "starting" || state === "running";
-        const inPanel = !!panel && panel.shown() === key;   // #1481: the panel shows this block; the card points there
-        run.hidden = !a.ok || going || inPanel;
-        if (toPanel) toPanel.hidden = inPanel;
-        stopB.hidden = !going;
-        banner.hidden = !going;
-        note.textContent = reason != null ? reason : going ? (state === "starting" ? tr("chat.pvStarting") : "") : inPanel ? tr("chat.pvInPanel") : a.ok ? "" : a.reason;
-        optB.textContent = P().optedIn() ? tr("chat.pvDisallow") : tr("chat.pvAllow");
-        neverB.textContent = P().never() ? tr("chat.pvNeverUndo") : tr("chat.pvNever");
-      };
-      const ui = { state: (name, reason) => { state = name === "starting" || name === "running" ? name : "idle"; refresh(reason || null); } };
-      run.onclick = () => P().start(key, holder, fence.code, ui);
-      stopB.onclick = () => P().stop(key, "stopped", "");
-      // A running preview moves: it stops here and starts in the panel (the click that ran it). An idle one opens the
-      // panel with its own Preview to click.
-      if (toPanel) toPanel.onclick = () => {
-        const moving = P().running(key);
-        if (moving) P().stop(key, "stopped", "");
-        panel.open({ key, instance: x.instance, msgKey: msgKey(x), n, code: fence.code, sender: x.sender, ts: x.ts }, { run: moving });
-      };
-      dl.onclick = () => opts.download(fence.code);
-      optB.onclick = () => { menu.open = false; opts.setPreviewOptIn(!P().optedIn()); };
-      neverB.onclick = () => { menu.open = false; P().setNever(!P().never()); refreshCards(); };
-      cardRefresh.set(ph, refresh);
-      refresh(stoppedKeys.includes(key) ? tr("chat.pvChanged") : null);
+      buildCard(ph, x, `${msgKey(x)}:f${n}`, { n, code: fence.code }, stoppedKeys);
+    }
+    const atts = Array.isArray(x.attachments) ? x.attachments : [];
+    for (const ph of node.querySelectorAll(".html-card[data-att]")) {
+      const att = atts.find(a => a && a.id === ph.dataset.att);
+      if (!att || !R().isHtmlAttachment(att)) continue;
+      ph.textContent = "";
+      buildCard(ph, x, `${msgKey(x)}:a${att.id}`, { att: { id: att.id, name: att.name, size: att.size } }, stoppedKeys);
     }
   }
+  /** Why an attachment's HTML could not be read, for the card's note. */
+  const attReason = (reason) => tr(reason === "over" ? "chat.pvAttOver" : reason === "gone" ? "chat.pvAttGone" : "chat.pvAttFailed");
+  /** One card: `source` is { n, code } for a fence or { att } for an attachment (its HTML read on the first click). */
+  function buildCard(ph, x, key, source, stoppedKeys) {
+    const doc = list.ownerDocument;
+    const el = (tag, cls, text) => { const e = doc.createElement(tag); if (cls) e.className = cls; if (text != null) e.textContent = text; return e; };
+    const att = source.att || null;
+    let code = att ? null : source.code;
+    const head = el("div", "pv-head");
+    const label = el("span", "pv-label", att ? `${tr("chat.pvHtml")} · ${att.name}` : tr("chat.pvHtml"));
+    const run = el("button", "btn btn-sm pv-run", tr("chat.pvPreview")); run.type = "button";
+    const stopB = el("button", "btn btn-sm pv-stop", tr("chat.pvStop")); stopB.type = "button"; stopB.hidden = true;
+    // An attachment already has its download link (the file itself) right above the card.
+    const dl = att ? null : el("button", "btn btn-sm btn-ghost pv-dl", tr("chat.pvDownload"));
+    if (dl) dl.type = "button";
+    const panel = opts.panel || null;
+    const toPanel = panel ? el("button", "btn btn-sm btn-ghost pv-open", tr("chat.pvOpenPanel")) : null;
+    if (toPanel) toPanel.type = "button";
+    const menu = el("details", "pv-menu");
+    const sum = el("summary", null, "⋯"); sum.title = tr("chat.pvMenu"); sum.setAttribute("aria-label", tr("chat.pvMenu"));
+    const optB = el("button", "chip-btn pv-opt"); optB.type = "button";
+    const neverB = el("button", "chip-btn pv-never"); neverB.type = "button";
+    menu.append(sum, optB, neverB);
+    head.append(label, run, stopB, ...(toPanel ? [toPanel] : []), ...(dl ? [dl] : []), menu);
+    const note = el("div", "pv-note");
+    const banner = el("div", "pv-banner", P().BANNER); banner.hidden = true;
+    const holder = el("div", "pv-holder");
+    ph.append(head, note, banner, holder);
+    let state = "idle";
+    // Reading an attachment: one read per card at a time (a second click while it reads does nothing), and a read
+    // whose card was stopped, replaced or left meanwhile is dropped (`reading` moved on, or the card left the page).
+    let reading = 0, reads = 0;
+    const refresh = (reason) => {
+      const a = P().availability();
+      const going = state === "starting" || state === "running";
+      const inPanel = !!panel && panel.shown() === key;   // #1481: the panel shows this block; the card points there
+      run.hidden = !a.ok || going || inPanel || !!reading;
+      if (toPanel) toPanel.hidden = inPanel || !!reading;
+      stopB.hidden = !going && !reading;
+      banner.hidden = !going;
+      note.textContent = reason != null ? reason : reading ? tr("chat.pvLoading") : going ? (state === "starting" ? tr("chat.pvStarting") : "") : inPanel ? tr("chat.pvInPanel") : a.ok ? "" : a.reason;
+      optB.textContent = P().optedIn() ? tr("chat.pvDisallow") : tr("chat.pvAllow");
+      neverB.textContent = P().never() ? tr("chat.pvNeverUndo") : tr("chat.pvNever");
+    };
+    /** The HTML, then `then(code)`: at once for a fence or an attachment already read; otherwise read it first. */
+    const withCode = async (then) => {
+      if (code != null) { then(code); return; }
+      if (reading) return;
+      const mine = reading = ++reads;
+      refresh();
+      const r = await loadHtmlAttachment(att);
+      if (reading !== mine || !ph.isConnected) return;
+      reading = 0;
+      if (!r.ok) { refresh(attReason(r.reason)); return; }
+      code = r.code;
+      refresh();
+      then(code);
+    };
+    const ui = { state: (name, reason) => { state = name === "starting" || name === "running" ? name : "idle"; refresh(reason || null); } };
+    // Nothing is read for Preview on a device that does not allow previews: the button is not even shown there.
+    run.onclick = () => { if (P().availability().ok) withCode((c) => P().start(key, holder, c, ui)); };
+    stopB.onclick = () => { if (reading) { reading = 0; refresh(); } else P().stop(key, "stopped", ""); };
+    // A running preview moves: it stops here and starts in the panel (the click that ran it). An idle one opens the
+    // panel with its own Preview to click.
+    if (toPanel) toPanel.onclick = () => {
+      const moving = P().running(key);
+      if (moving) P().stop(key, "stopped", "");
+      withCode((c) => panel.open({ key, instance: x.instance, msgKey: msgKey(x), ...(att ? { att } : { n: source.n }), code: c, sender: x.sender, ts: x.ts }, { run: moving }));
+    };
+    if (dl) dl.onclick = () => opts.download(code);
+    optB.onclick = () => { menu.open = false; opts.setPreviewOptIn(!P().optedIn()); };
+    neverB.onclick = () => { menu.open = false; P().setNever(!P().never()); refreshCards(); };
+    cardRefresh.set(ph, refresh);
+    refresh(stoppedKeys.includes(key) ? tr("chat.pvChanged") : null);
+  }
   /** Re-read this device's preview choice on every card in this thread. */
   function refreshCards() {
-    for (const node of list.querySelectorAll(".html-card[data-card]")) { const f = cardRefresh.get(node); if (f) f(); }
+    for (const node of list.querySelectorAll(".html-card[data-card], .html-card[data-att]")) { const f = cardRefresh.get(node); if (f) f(); }
   }
 
   const nearBottom = () => R().isNearBottom(scroller.scrollTop, scroller.clientHeight, scroller.scrollHeight);
@@ -233,6 +286,10 @@ export function createThread(list, scroller, opts) {
       const folded = box.classList.toggle("folded");
       el.textContent = folded ? trf("chat.showAll", el.dataset.lines) : tr("chat.showLess");
     } else if (act === "toggleWrap") opts.toggleWrap();
+    else if (act === "replyButton") {
+      const m = /^([0-9a-f]{32}):(\d{1,2})$/.exec(el.dataset.arg || "");
+      if (m && opts.clickReplyButton) opts.clickReplyButton(m[1], Number(m[2]));
+    }
   }
 
   /** The thread goes (the chat left, or another instance opened): every preview in it stops first. */

package/dist/ui/first-run.js

@@ -0,0 +1,64 @@
+// #1519 P7 (docs/design/ux-onboarding-walkthrough.md §5.1): the first-run card. A fleet with no chat connection (a
+// web-only fleet) opens Chat and Settings with it: "Connect a chat app" opens the setup wizard (in Settings, where its
+// progress is shown), "Use the web only" hides it in this browser. It stays until a connection exists or it is dismissed.
+import { html } from "/assets/app-html.js";
+import { register, t } from "/assets/app-i18n.js";
+import { appStore, createStore, useStore } from "/assets/app-store.js";
+import { navigate } from "/assets/app-nav.js";
+import { settingsPath } from "/assets/app-route.js";
+import { Icon } from "/assets/ui-icons.js";
+
+register("firstRun", {
+  en: {
+    title: "Connect a chat app",
+    body: "AgEnD works in this browser on its own. To talk to your agents from Telegram or Discord too, add a bot: the setup wizard checks its token and connects it to an agent.",
+    connect: "Connect a chat app", webOnly: "Use the web only",
+  },
+  "zh-TW": {
+    title: "連接聊天應用程式",
+    body: "AgEnD 只用這個瀏覽器也能運作。想同時從 Telegram 或 Discord 跟你的 agent 對話，就加一個機器人：設定精靈會檢查它的 token，並把它接到一個 agent。",
+    connect: "連接聊天應用程式", webOnly: "只用網頁",
+  },
+});
+
+export const DISMISS_KEY = "agend_firstrun_dismissed";
+function readDismissed() { try { return localStorage.getItem(DISMISS_KEY) === "1"; } catch { return false; } }
+// `dismissed`: this page's own answer (it holds even when the browser keeps no storage); a stored one is read each time.
+const local = createStore({ dismissed: false, wizard: false });
+
+export function dismissFirstRun() {
+  try { localStorage.setItem(DISMISS_KEY, "1"); } catch { /* this page only */ }
+  local.set({ dismissed: true });
+}
+
+/** For the tests: a fresh page's state. */
+export function resetFirstRun() { local.set({ dismissed: false, wizard: false }); }
+
+/** Settings asks once, when it has its data: was it opened by "Connect a chat app" (open the wizard)? */
+export function takeWizardRequest() {
+  if (!local.get().wizard) return false;
+  local.set({ wizard: false });
+  return true;
+}
+
+/** Shown on a known web-only fleet (no connection) until dismissed. */
+export function useFirstRun() {
+  const app = useStore(appStore);
+  const { dismissed } = useStore(local);
+  return app.ready && app.connections === 0 && !dismissed && !readDismissed();
+}
+
+/** onConnect: Settings opens its wizard in place; elsewhere the card goes to Settings, which opens it. */
+export function FirstRunCard({ onConnect }) {
+  const shown = useFirstRun();
+  if (!shown) return null;
+  const connect = onConnect || (() => { local.set({ wizard: true }); navigate(settingsPath("bots")); });
+  return html`<section class="card first-run" aria-labelledby="first-run-title">
+    <h3 id="first-run-title"><${Icon} name="plug" size=${14} /> ${t("firstRun.title")}</h3>
+    <p>${t("firstRun.body")}</p>
+    <div class="dlg-inline-actions">
+      <button type="button" class="btn btn-primary" onClick=${connect}>${t("firstRun.connect")}</button>
+      <button type="button" class="btn btn-ghost" onClick=${dismissFirstRun}>${t("firstRun.webOnly")}</button>
+    </div>
+  </section>`;
+}

package/dist/ui/html-attachment.js

@@ -0,0 +1,26 @@
+// #1306 §6.1 (Q4): an agent's .html / .htm attachment gets the same preview card as a ```html block. Its HTML is read
+// from /ui/file/<id> — same origin, this session's cookie — only on a click (Preview, Open in panel), never to show a
+// card. What runs is then handed to the preview frame exactly like a block's (AgendPreview.start): the file URL itself
+// is never opened or framed on the dashboard's origin.
+
+/** The same cap as a block's (preview.js LIMITS.maxBytes): UTF-8 bytes of the HTML. */
+export const HTML_ATTACHMENT_MAX = 1024 * 1024;
+
+/**
+ * Read an attachment's HTML: { ok: true, code } or { ok: false, reason } with reason "over" (the file is over the
+ * cap: its listed size is checked before anything is fetched, the bytes again after), "gone" (the fleet no longer
+ * serves that id — the file changed, or the fleet restarted), or "failed".
+ */
+export async function loadHtmlAttachment(att, fetchImpl = globalThis.fetch) {
+  if (!att || typeof att.id !== "string" || !/^[0-9a-f]{32}$/.test(att.id)) return { ok: false, reason: "failed" };
+  if (typeof att.size === "number" && att.size > HTML_ATTACHMENT_MAX) return { ok: false, reason: "over" };
+  let res;
+  try { res = await fetchImpl(`/ui/file/${att.id}`, { credentials: "same-origin", cache: "no-store" }); }
+  catch { return { ok: false, reason: "failed" }; }
+  if (!res || !res.ok) return { ok: false, reason: res && res.status === 404 ? "gone" : "failed" };
+  let bytes;
+  try { bytes = await res.arrayBuffer(); } catch { return { ok: false, reason: "failed" }; }
+  if (bytes.byteLength > HTML_ATTACHMENT_MAX) return { ok: false, reason: "over" };
+  // UTF-8, as a block's text is; a BOM is dropped.
+  return { ok: true, code: new TextDecoder("utf-8").decode(bytes) };
+}

package/dist/ui/panel-chat.js

@@ -10,7 +10,7 @@ import { html, useEffect, useLayoutEffect, useRef, useState } from "/assets/app-
 import { t } from "/assets/app-i18n.js";
 import { appStore, useStore } from "/assets/app-store.js";
 import { useLease } from "/assets/app-ctx.js";
-import { PanelHeader, onPanelKey, setTitle, addFooterItem, statusClass, statusLabel, openDrawer } from "/assets/app-shell.js";
+import { PanelHeader, onPanelKey, setTitle, addFooterItem, statusClass, statusLabel, openDrawer, requestNewInstance } from "/assets/app-shell.js";
 import { navigate } from "/assets/app-nav.js";
 import { Menu } from "/assets/ui-menu.js";
 import { Dialog } from "/assets/ui-dialog.js";
@@ -25,6 +25,7 @@ import { createThread, msgKey } from "./chat-thread.js";
 import { PreviewPanel, openPanel, panelStore, shownKey } from "./preview-panel.js";
 import { needsArgument, paletteFor, parseCommandLine } from "./chat-commands.js";
 import { installTour, refreshTourSpot, startTour } from "./chat-tour.js";
+import { FirstRunCard } from "./first-run.js";
 
 const R = () => globalThis.AgendChatRender;
 const P = () => globalThis.AgendPreview;
@@ -99,9 +100,9 @@ async function copyText(text) {
   return ok;
 }
 /** The HTML as a file: a blob of the source as application/octet-stream, saved as reply.html — never opened. */
-function downloadHtml(code) {
+function downloadHtml(code, name) {
   const url = URL.createObjectURL(new Blob([code], { type: "application/octet-stream" }));
-  const a = document.createElement("a"); a.href = url; a.download = "reply.html"; a.className = "offscreen";
+  const a = document.createElement("a"); a.href = url; a.download = typeof name === "string" && name.trim() ? name.trim() : "reply.html"; a.className = "offscreen";
   document.body.appendChild(a); a.click(); a.remove();
   URL.revokeObjectURL(url);
 }
@@ -127,9 +128,14 @@ export function ChatPanel({ route, navKey }) {
   }, [name, !!inst]);
   useEffect(() => { setTitle(name || t("app.chat")); }, [name, navKey]);
   if (!name) {
+    // #1519 P7: a web-only fleet starts here with the first-run card; with no agent at all, the way to make one.
+    const none = app.ready && !app.instances.length;
     return html`<div class="panel p-chat"><${PanelHeader} title=${t("app.chat")} />
-      <div class="panel-body center"><${Empty} icon="chat" title=${t("chat.pick")} hint=${t("chat.pickHint")}
-        action=${html`<button type="button" class="btn only-narrow" onClick=${openDrawer}>${t("chat.backToList")}</button>`} /></div></div>`;
+      <div class="panel-body center"><div class="first-run-stack"><${FirstRunCard} />
+        ${none ? html`<${Empty} icon="bot" title=${t("app.noInstances")} hint=${t("app.noInstancesHint")}
+          action=${html`<button type="button" class="btn btn-primary" onClick=${requestNewInstance}><${Icon} name="plus" size=${16} />${t("app.newInstance")}</button>`} />`
+        : html`<${Empty} icon="chat" title=${t("chat.pick")} hint=${t("chat.pickHint")}
+          action=${html`<button type="button" class="btn only-narrow" onClick=${openDrawer}>${t("chat.backToList")}</button>`} />`}</div></div></div>`;
   }
   if (!app.ready) return html`<div class="panel p-chat"><${PanelHeader} title=${name} /><div class="panel-body"><${Skeleton} lines=${5} /></div></div>`;
   if (!inst) return html`<${NotFound} name=${name} />`;
@@ -221,6 +227,8 @@ function Thread({ name, th }) {
     const thread = createThread(list.current, scroller.current, {
       t, tf: t, isUser: (x) => store.isUser(x, name), onJump: setJump, onEmpty: setEmpty,
       setPreviewOptIn, copyText, download: downloadHtml, toggleWrap,
+      clickReplyButton: (id, index) => store.clickReplyButton(name, id, index),      // #1266
+      replyButtonBusy: (id) => store.state.rbBusy.has(id),
       panel: { shown: shownKey, open: (spec, o) => openPanel(spec, o) },   // #1481
     });
     th.current = thread;

package/dist/ui/panel-fleet.js

@@ -36,8 +36,8 @@ register("fleet", {
     channel: "Channel", type: "Type", tokenEnv: "Bot token env", groupId: "Group ID", show: "Show", hide: "Hide", access: "Access control", mode: "Mode", locked: "Locked", open: "Open",
     allowedUsers: "Allowed users", allowedUsersNote: "Comma-separated user IDs", defaults: "Defaults", backend: "Backend", roots: "Project roots", addRoot: "Add root", removeRoot: "Remove",
     saveNote: "Saving rewrites fleet.yaml (its comments are lost).",
-    newInstance: "New instance", directory: "Directory", directoryHint: "Optional — a workspace is created if empty", topic: "Topic name", topicHint: "From the directory name",
-    topicRequired: "Topic name is required when Directory is empty", description: "Description", descriptionHint: "What this instance does", model: "Model", modelHint: "e.g. sonnet, opus, gpt-5",
+    newInstance: "New instance", directory: "Directory", directoryHint: "Optional — a workspace is created if empty", topic: "Name", topicHint: "From the directory name",
+    topicRequired: "Name is required when Directory is empty", description: "Description", descriptionHint: "What this instance does", model: "Model", modelHint: "e.g. sonnet, opus, gpt-5",
     branch: "Branch (git worktree)", branchHint: "e.g. feature-x", tags: "Tags", tagsHint: "comma-separated, e.g. dev, review", systemPrompt: "System prompt", systemPromptHint: "Custom instructions for this instance",
     fleetDefault: "Use the fleet default", notInstalled: "(not installed)", deprecated: "(deprecated)", instanceCreated: "Instance created",
   },
@@ -56,8 +56,8 @@ register("fleet", {
     channel: "頻道", type: "類型", tokenEnv: "Bot token 環境變數", groupId: "Group ID", show: "顯示", hide: "隱藏", access: "存取控制", mode: "模式", locked: "鎖定", open: "開放",
     allowedUsers: "允許的使用者", allowedUsersNote: "以逗號分隔的使用者 ID", defaults: "預設值", backend: "Backend", roots: "專案根目錄", addRoot: "新增根目錄", removeRoot: "移除",
     saveNote: "儲存會改寫 fleet.yaml（其中的註解會遺失）。",
-    newInstance: "新增 instance", directory: "目錄", directoryHint: "可留空——留空會自動建立工作區", topic: "Topic 名稱", topicHint: "預設取自目錄名稱",
-    topicRequired: "目錄留空時必須填寫 Topic 名稱", description: "說明", descriptionHint: "這個 instance 做什麼", model: "模型", modelHint: "例如 sonnet、opus、gpt-5",
+    newInstance: "新增 instance", directory: "目錄", directoryHint: "可留空——留空會自動建立工作區", topic: "名稱", topicHint: "預設取自目錄名稱",
+    topicRequired: "目錄留空時必須填寫名稱", description: "說明", descriptionHint: "這個 instance 做什麼", model: "模型", modelHint: "例如 sonnet、opus、gpt-5",
     branch: "分支（git worktree）", branchHint: "例如 feature-x", tags: "標籤", tagsHint: "以逗號分隔，例如 dev, review", systemPrompt: "System prompt", systemPromptHint: "這個 instance 的自訂指示",
     fleetDefault: "使用 fleet 預設", notInstalled: "（未安裝）", deprecated: "（已淘汰）", instanceCreated: "Instance 已建立",
   },
@@ -359,7 +359,7 @@ function CreateTeam({ onClose, onDone }) {
   </${FormDialog}>`;
 }
 
-/** "New instance": the sidebar's ✎ opens it from anywhere (#1408 step 3 merges it with Settings' create flow). */
+/** "New instance": the sidebar's + opens it from anywhere (#1408 step 3 merges it with Settings' create flow). */
 export function CreateInstanceDialog({ onClose }) {
   const lease = useLease("create-instance");
   const [backends, setBackends] = useState(null);

package/dist/ui/panel-settings.js

@@ -25,7 +25,7 @@ import { api, attach, confirmedWrite, newKey } from "./settings-confirm.js";
 import { dismissOperation, operationActive, restartFleet, startOperation, takeLeftover } from "./settings-apply.js";
 import {
   ACCESS_MODES, AGENT_MODES, DEFAULT_SCHEMA, LOG_LEVELS, TOOL_PROGRESS, TOOL_SETS, VISIBILITY_MODES, batchImpact,
-  changedFields, channelId, channelsOf, chLabel, effectiveSummary, fleetModel, fromYaml, fullModelRequests, groupAgents,
+  changedFields, channelId, channelsOf, chLabel, connectionState, effectiveSummary, fleetModel, fromYaml, fullModelRequests, groupAgents,
   hasOwn, impactOf, localeOptions, defaultsImpact, requestImpact, nonNegative, positive, replyGuardSupported, shortName, STATUS_ORDER, toYaml,
   visibilityDefault, worstImpact,
 } from "./settings-model.js";
@@ -35,6 +35,7 @@ import {
 } from "./settings-dialogs.js";
 import { SetupWizard } from "./settings-wizard.js";
 import { CreateInstanceDialog } from "./panel-fleet.js";
+import { FirstRunCard, takeWizardRequest } from "./first-run.js";
 
 const tn = (k, ...v) => t(`settings.${k}`, ...v);
 const ICONS = { agents: "bot", bots: "plug", classic: "room", general: "sliders", advanced: "code" };
@@ -197,6 +198,8 @@ export function SettingsPanel({ route, navKey }) {
   };
 
   const ctx = data && !data.error ? makeCtx(data, setData, stage, unstage, reload, reloadLive, () => mount.current()) : null;
+  // #1519 P7: "Connect a chat app" on the first-run card elsewhere came here for the wizard: it opens once the data is in.
+  useEffect(() => { if (ctx && takeWizardRequest()) setDialog({ kind: "wizard", key: navKey }); }, [!!ctx, navKey]);
   const sectionBody = !data ? html`<${Skeleton} lines=${6} />`
     : data.error ? html`<${ErrorState} message=${tn("configLoadFailed")} onRetry=${reload} />`
     : section === "agents" ? html`<${Agents} ctx=${ctx} search=${search} openDialog=${(d) => setDialog({ ...d, key: navKey })} />`
@@ -220,6 +223,7 @@ export function SettingsPanel({ route, navKey }) {
         <input type="search" value=${search} placeholder=${tn("searchAll")} onInput=${(e) => setSearch(e.target.value)} /></label></div>` : null}
       ${op ? html`<${OperationCard} op=${op} schema=${data && data.schema} />` : null}
       <${PendingChanges} inline=${true} />
+      ${ctx && (section === "agents" || section === "bots") ? html`<${FirstRunCard} onConnect=${() => setDialog({ kind: "wizard", key: navKey })} />` : null}
       ${sectionBody}
     </div></div>
     ${staged.size ? html`<${PendingBar} staged=${staged} busy=${opBusy(op)} onApply=${apply} onDiscard=${discard} />` : null}
@@ -378,7 +382,12 @@ function Bots({ ctx, search, openDialog }) {
   return html`${head}
     ${!rows.length ? html`<${Empty} icon="plug" title=${needle ? tn("noAgentMatch", search.trim()) : tn("noBots")} />` : html`<div class="s-list">${rows.map(({ ch, i }) => {
       const users = (ch.access && ch.access.allowed_users) || [];
-      const token = (ctx.connections.find((c, j) => channelId(c, j) === channelId(ch, i)) || {}).token_present;
+      const meta = ctx.connections.find((c, j) => channelId(c, j) === channelId(ch, i)) || {};
+      const token = meta.token_present;
+      // #1519 P6: this connection's own state (not the fleet's "Connected") — a stopped one says so; a known problem says
+      // what to do (P3: Message Content intent; a rejected token).
+      const state = connectionState(meta, ctx.fleetUp);
+      const stateText = tn(state.key, state.bot);
       // #1408 step 5: one line on a desktop — who it is, its facts in one clipped line (all of them in its tooltip),
       // then the cluster; on a phone the facts go under it. It no longer wraps fact by fact.
       const facts = [ch.bot_token_env || tn("noTokenEnv"),
@@ -386,13 +395,13 @@ function Bots({ ctx, search, openDialog }) {
         tn("accessTag", (ch.access && ch.access.mode) || "locked"),
         users.length ? `${users.slice(0, 3).join(", ")}${users.length > 3 ? ` +${users.length - 3}` : ""}` : tn("noAllowedUsers")].filter(Boolean).join(" · ");
       return html`<div key=${channelId(ch, i)} class="s-row s-conn">
-        <span class="s-ident"><span class=${`dot ${ctx.fleetUp ? "ok" : "bad"}`} title=${ctx.fleetUp ? tn("connected") : tn("problem")} aria-hidden="true"></span>
+        <span class="s-ident"><span class=${`dot ${state.cls}`} title=${stateText} aria-hidden="true"></span>
           <span class="s-name">${ch.type === "telegram" ? "Telegram" : "Discord"}</span>
           <span class=${`tag${i === 0 ? "" : " persona"}`}>${ch.id || chLabel(i)}</span></span>
         <span class="s-facts" title=${facts}>${facts}</span>
         <span class="s-actions">
           <span class=${`tag${token ? "" : " warn"}`}>${token ? tn("tokenConfigured") : tn("tokenMissing")}</span>
-          <span class=${`s-state ${ctx.fleetUp ? "ok" : "bad"}`}>${ctx.fleetUp ? tn("connected") : tn("problem")}</span>
+          <span class=${`s-state ${state.cls}`} title=${stateText}>${stateText}</span>
           <button type="button" class="btn btn-sm" onClick=${() => openDialog({ kind: "bot", id: channelId(ch, i) })}>${tn("settingsButton")}</button></span>
       </div>`;
     })}</div>`}
@@ -671,7 +680,7 @@ function Developer({ ctx }) {
         ${["yaml", "json"].map((k) => html`<button key=${k} type="button" class=${`btn btn-sm${fmt === k ? " on" : ""}`} aria-pressed=${fmt === k ? "true" : "false"} onClick=${() => setFmt(k)}>${k.toUpperCase()}</button>`)}</div>
       <button type="button" class="btn btn-sm" onClick=${() => setEditing(!editing)}>${editing ? tn("viewMode") : tn("editMode")}</button>
       <button type="button" class="btn btn-sm" title=${tn("copy")} onClick=${copy}><${Icon} name="copy" size=${14} /><span class="lbl">${tn("copy")}</span></button>
-      <button type="button" class="btn btn-sm" title="fleet.yaml" onClick=${download}><${Icon} name="download" size=${14} /><span class="lbl">fleet.yaml</span></button>
+      <button type="button" class="btn btn-sm" title=${tn("devDownload")} onClick=${download}><${Icon} name="download" size=${14} /><span class="lbl">${tn("devDownload")}</span></button>
     </div>
     ${editing ? html`<textarea class="s-yaml" aria-label=${tn("devEditor")} spellcheck="false" wrap="off" value=${draft} onInput=${(e) => setDraft(e.target.value)}></textarea>
         <div class="save-row"><button type="button" class="btn btn-primary" onClick=${save}>${tn("devApply")}</button><span class="note">${tn("devApplyHint")}</span></div>`
@@ -699,7 +708,8 @@ function OperationCard({ op, schema }) {
   const phaseBusy = ["writing", "posting", "watching"].includes(op.phase);
   const job = op.job;
   const rows = (job && job.targets) || [];
-  const fleetRestarting = job && job.status === "running" && rows.some((r) => r.target === "fleet" && r.status === "running");
+  // A fleet row of kind "hot" is connections starting without a restart (#1519 P6), not AgEnD restarting.
+  const fleetRestarting = job && job.status === "running" && rows.some((r) => r.target === "fleet" && r.status === "running" && r.kind !== "hot");
   const needsRestart = rows.some((r) => r.status === "restart-required");
   const failedRows = rows.some((r) => r.status === "failed");
   const mismatch = schema && schema.fleet_signature_mismatch;
@@ -732,11 +742,11 @@ function OperationCard({ op, schema }) {
     ${op.steps.length ? html`<ul class="s-op-steps">${op.steps.map((s, i) => html`<li key=${i} class=${`s-step ${s.status}`}>
       <span class="s-step-icon" aria-hidden="true">${icon(s.status) ? html`<${Icon} name=${icon(s.status)} size=${14} />` : "·"}</span>
       <span class="grow">${s.label}</span>
-      <span class="note">${s.status === "waiting" ? tn("stepWaiting") : s.status === "skipped" ? tn("stepSkipped") : s.status === "failed" ? (s.error || tn("applyFailed")) : impactText(s.impact)}</span></li>`)}</ul>` : null}
+      <span class="note">${s.status === "waiting" ? tn("stepWaiting") : s.status === "skipped" ? tn("stepSkipped") : s.status === "failed" ? (s.error || tn("applyFailed")) : s.note || impactText(s.impact)}</span></li>`)}</ul>` : null}
     ${rows.length ? html`<ul class="s-op-steps">${rows.map((r) => html`<li key=${r.target} class=${`s-step ${r.status}`}>
       <span class="s-step-icon" aria-hidden="true">${r.status === "done" ? html`<${Icon} name="check" size=${14} />` : r.status === "failed" ? html`<${Icon} name="alert" size=${14} />` : r.status === "restart-required" ? html`<${Icon} name="restart" size=${14} />` : "·"}</span>
       <span class="grow">${r.target === "fleet" ? "AgEnD" : shortName(r.target, {})}</span>
-      <span class="note">${r.target === "fleet" && r.status === "running" ? tn("restartFleetTitle") : r.status === "restart-required" ? tn("applyRestartNeeded")
+      <span class="note">${r.target === "fleet" && r.status === "running" ? tn(r.kind === "hot" ? "connStartingNow" : "restartFleetTitle") : r.status === "restart-required" ? tn("applyRestartNeeded")
         : r.settled_by === "no-change" ? tn("applyNoChange") : r.settled_by === "fleet-restart" ? tn("viaRestart") : r.kind === "hot" ? tn("impactNow") : tn("impactAgent")}</span>
       ${r.error ? html`<span class="feedback error">${r.error}</span>` : null}</li>`)}</ul>` : null}
     ${job && job.error ? html`<p class="feedback error">${job.error}</p>` : null}

package/dist/ui/preview-panel.js

@@ -12,13 +12,14 @@ 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, code, sender, ts } | null; run: start it on mount (a moved run). */
+/** 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 */ } } }
@@ -54,6 +55,22 @@ 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];
@@ -93,6 +110,8 @@ export function PreviewPanel({ name, split, msgs, subscribe, keyOf, reveal, down
   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;
 
@@ -120,6 +139,7 @@ export function PreviewPanel({ name, split, msgs, subscribe, keyOf, reveal, down
   }, [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();
@@ -162,6 +182,21 @@ export function PreviewPanel({ name, split, msgs, subscribe, keyOf, reveal, down
     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(); } };
 
@@ -188,10 +223,10 @@ export function PreviewPanel({ name, split, msgs, subscribe, keyOf, reveal, down
         ${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)}><${Icon} name="download" size=${14} /><span class="lbl">${t("chat.pvDownload")}</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=${() => openPanel(newer)}>${t("chat.pvNewerShow")}</button></div>` : null}
+        <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" : ""}`}>

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" } };
 }