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

package/dist/ui/settings-strings.js

@@ -62,7 +62,7 @@ register("settings", {
     se_primaryServer: "primary",
     se_externalEmojiHint: "Another server's emoji needs the bot's Use External Emojis permission in the channel it reacts in.",
     se_unavailable: "unavailable",
-    se_hint: "Empty keeps the default. The preview is resolved by AgEnD exactly as the bot will react.",
+    se_hint: "Empty keeps the default. The preview is resolved by AgEnD exactly as the bot will react. Progress prefix is not a reaction: it starts the progress message.",
     detection: "Detection",
     startup: "Startup",
     backendSection: "Backend",
@@ -100,7 +100,18 @@ register("settings", {
     tokenEnv: "Bot token env var",
     groupId: "Group / guild id",
     nameField: "Name",
-    envHint: "Put the actual token in ~/.agend/.env under this env var, then Reload Fleet.",
+    tokenShow: "Show the token", tokenHide: "Hide the token", tokenIsBot: "This is {0}.", tokenStatus: "Bot token",
+    tokenSet: "Token set", tokenSetAs: "Token set · {0}", tokenMissing: "Token missing", tokenReplace: "Replace",
+    tokenStoredAs: "The token is stored on this computer in ~/.agend/.env under this name — generated, and only needed if you manage .env yourself.",
+    tokenSavedRestart: "Token saved. This connection is not running, so it starts with the new token when AgEnD restarts (on the host: agend restart).",
+    newBotTokenHint: "Paste the bot's token. It is checked with the platform, then stored on this computer — never in the browser.",
+    connectionIdOptional: "Connection id (optional)",
+    connConnectedAs: "Connected · {0}", connReconnecting: "Reconnecting…", connStarting: "Starting…", connFailed: "Could not connect",
+    connNotRunning: "Not running", connTokenMissing: "Token missing", connRejected: "Token rejected — replace it",
+    discordInvite: "Invite {0} to your server", discordTheBot: "the bot", discordWaitingJoin: "Waiting for the bot to join a server…",
+    discordCheckAgain: "Check again", discordNoServerYet: "Invite the bot first, or type the server id",
+    discordIntentNote: "Turn on Message Content Intent for this bot in the Discord developer portal (it cannot be set from here):", discordPortalBot: "Developer portal → Bot",
+    discordMissingIntent: "Turn on Message Content Intent in the Discord developer portal → Bot, then restart AgEnD.",
     noAgents: "No agents yet — click + New.",
     noBots: "No bots configured.",
     currentVersion: "Current version",
@@ -123,7 +134,7 @@ register("settings", {
     wizardButton: "Setup wizard",
     wizardTitle: "Set up AgEnD",
     wizardStep: "Step {0} of {1}",
-    wizardRerun: "A fleet is already configured — finishing replaces the connection that uses the same token variable.",
+    wizardRerun: "A fleet is already configured — finishing adds a new connection; nothing already there is replaced.",
     wizardBack: "Back",
     wizardNext: "Next",
     wizardFinish: "Create and start",
@@ -131,6 +142,14 @@ register("settings", {
     wizardBackendFound: "Found on this host: {0}",
     wizardBackendNone: "No backend CLI found on this host — install one first.",
     wizardAgentName: "First agent name",
+    wizardAgentWhich: "Which agent answers on this bot",
+    wizardAgentNew: "A new agent",
+    wizardAgentExisting: "An agent you already have",
+    wizardAgentPick: "Agent",
+    wizardAgentExistingNote: "It keeps its directory, backend and settings; only its chat connection becomes this bot (if it has one now, it moves here).",
+    wizardAgentNewName: "New agent name",
+    wizardTopicNotCarried: "Its topic ({0}) is in the chat of its old connection, so it is not carried over: in the new chat it has no topic until one is bound.",
+    wizardTopicGeneral: "It is the General agent: in the new chat it takes that chat's General topic.",
     wizardNeedDir: "Enter an absolute working directory.",
     wizardTelegramHint: "Create a bot with @BotFather, then add it to a group.",
     wizardDiscordHint: "Create an application in the Discord developer portal and invite the bot to your server.",
@@ -165,7 +184,7 @@ register("settings", {
     restartFleetConfirm: "Restart AgEnD now?\n\nEvery agent stops and starts again, work in progress is interrupted, and the panel is unreachable for up to a minute. A notice is posted to your chat channel.",
     restartFleetStarted: "Restarting AgEnD — this page keeps checking.",
     restartFleetBusy: "Restarting…",
-    restartFleetTitle: "Restarting AgEnD…",
+    restartFleetTitle: "Restarting AgEnD…", connStartingNow: "Starting the new connection — no restart needed…",
     restartFleetWaiting: "AgEnD is restarting. This page keeps checking and will say when it is back — there is nothing to press.",
     working: "Working…",
     restartFleetRefused: "Restart refused: {0}",
@@ -217,6 +236,7 @@ register("settings", {
     countAgents: "{0} agents",
     countBots: "{0} connections",
     countRooms: "{0} rooms",
+    countAgent: "1 agent", countBot: "1 connection", countRoom: "1 room",
     newAgent: "New agent",
     newBot: "New connection",
     effortTag: "effort: {0}",
@@ -309,6 +329,7 @@ register("settings", {
     editMode: "Edit",
     viewMode: "View",
     copy: "Copy",
+    devDownload: "Download fleet.yaml",
     devEditor: "fleet.yaml editor",
     devApply: "Apply & save",
     devApplyHint: "Writes these settings and applies them, like Apply changes.",
@@ -351,7 +372,7 @@ register("settings", {
     se_primaryServer: "主伺服器",
     se_externalEmojiHint: "使用其他伺服器的 emoji，bot 在要加反應的頻道需有「使用外部表情符號」權限。",
     se_unavailable: "無法使用",
-    se_hint: "留空即使用預設值。預覽由 AgEnD 依 bot 實際 react 的方式解析。",
+    se_hint: "留空即使用預設值。預覽由 AgEnD 依 bot 實際 react 的方式解析。進度前綴不是反應，而是進度訊息開頭的 emoji。",
     title: "設定",
     myAgents: "我的 Agent",
     bots: "機器人",
@@ -423,7 +444,18 @@ register("settings", {
     tokenEnv: "Bot token 環境變數",
     groupId: "群組 / guild id",
     nameField: "名稱",
-    envHint: "把實際 token 放到 ~/.agend/.env 的這個環境變數下，然後點重新載入。",
+    tokenShow: "顯示 token", tokenHide: "隱藏 token", tokenIsBot: "這是 {0}。", tokenStatus: "Bot token",
+    tokenSet: "已設定 token", tokenSetAs: "已設定 token · {0}", tokenMissing: "缺少 token", tokenReplace: "更換",
+    tokenStoredAs: "token 存在這台電腦的 ~/.agend/.env，用這個名稱——自動產生，只有自行管理 .env 時才需要。",
+    tokenSavedRestart: "已儲存 token。這個連線目前沒有在執行，AgEnD 重新啟動時會用新的 token 啟動（在主機上：agend restart）。",
+    newBotTokenHint: "貼上 bot 的 token。會先向平台確認，再存到這台電腦——絕不存在瀏覽器。",
+    connectionIdOptional: "連線 id（選填）",
+    connConnectedAs: "已連線 · {0}", connReconnecting: "重新連線中…", connStarting: "啟動中…", connFailed: "無法連線",
+    connNotRunning: "未執行", connTokenMissing: "缺少 token", connRejected: "token 被拒——請更換",
+    discordInvite: "邀請 {0} 加入你的伺服器", discordTheBot: "bot", discordWaitingJoin: "等待 bot 加入伺服器…",
+    discordCheckAgain: "再檢查一次", discordNoServerYet: "請先邀請 bot，或輸入伺服器 id",
+    discordIntentNote: "請在 Discord 開發者入口網站為這個 bot 開啟 Message Content Intent（這裡無法代為設定）：", discordPortalBot: "開發者入口網站 → Bot",
+    discordMissingIntent: "請到 Discord 開發者入口網站 → Bot 開啟 Message Content Intent，然後重新啟動 AgEnD。",
     noAgents: "還沒有 agent — 點 + 新增。",
     noBots: "尚未設定機器人。",
     currentVersion: "目前版本",
@@ -446,7 +478,7 @@ register("settings", {
     wizardButton: "設定精靈",
     wizardTitle: "設定 AgEnD",
     wizardStep: "第 {0} 步，共 {1} 步",
-    wizardRerun: "已經有設定好的 fleet —— 完成後會取代使用相同 token 變數的那個連線。",
+    wizardRerun: "已經有設定好的 fleet —— 完成後會新增一個連線，不會取代任何既有的設定。",
     wizardBack: "上一步",
     wizardNext: "下一步",
     wizardFinish: "建立並啟動",
@@ -454,6 +486,14 @@ register("settings", {
     wizardBackendFound: "在這台主機上找到：{0}",
     wizardBackendNone: "這台主機上找不到任何後端 CLI —— 請先安裝一個。",
     wizardAgentName: "第一個 agent 名稱",
+    wizardAgentWhich: "由哪個 agent 在這個機器人上回覆",
+    wizardAgentNew: "新的 agent",
+    wizardAgentExisting: "既有的 agent",
+    wizardAgentPick: "Agent",
+    wizardAgentExistingNote: "它的目錄、backend 和設定都不變；只有聊天連線改成這個機器人（如果它目前已有連線，會移到這裡）。",
+    wizardAgentNewName: "新 agent 名稱",
+    wizardTopicNotCarried: "它的 topic（{0}）屬於舊連線的聊天室，不會帶過去：在新的聊天室裡，綁定新的 topic 之前它沒有 topic。",
+    wizardTopicGeneral: "它是 General agent：在新的聊天室裡會改用那裡的 General topic。",
     wizardNeedDir: "請輸入絕對路徑的工作目錄。",
     wizardTelegramHint: "用 @BotFather 建立 bot，然後把它加進一個群組。",
     wizardDiscordHint: "在 Discord 開發者後台建立應用程式，並把 bot 邀請到你的伺服器。",
@@ -488,7 +528,7 @@ register("settings", {
     restartFleetConfirm: "現在重新啟動 AgEnD？\n\n所有 agent 都會停止再啟動，進行中的工作會被中斷，面板會有最多約一分鐘無法連線。聊天頻道會收到一則通知。",
     restartFleetStarted: "AgEnD 重新啟動中 —— 此頁面會持續確認。",
     restartFleetBusy: "重啟中…",
-    restartFleetTitle: "AgEnD 重新啟動中…",
+    restartFleetTitle: "AgEnD 重新啟動中…", connStartingNow: "正在啟動新連線——不需要重新啟動…",
     restartFleetWaiting: "AgEnD 正在重新啟動。此頁面會持續確認，恢復後會告訴你 —— 不需要再按任何按鈕。",
     working: "執行中…",
     restartFleetRefused: "重新啟動被拒絕：{0}",
@@ -540,6 +580,7 @@ register("settings", {
     countAgents: "{0} 個 agent",
     countBots: "{0} 個連線",
     countRooms: "{0} 個房間",
+    countAgent: "1 個 agent", countBot: "1 個連線", countRoom: "1 個房間",
     newAgent: "新增 agent",
     newBot: "新增連線",
     effortTag: "effort：{0}",
@@ -632,6 +673,7 @@ register("settings", {
     editMode: "編輯",
     viewMode: "檢視",
     copy: "複製",
+    devDownload: "下載 fleet.yaml",
     devEditor: "fleet.yaml 編輯器",
     devApply: "套用並儲存",
     devApplyHint: "寫入這些設定並套用，和「套用變更」相同。",

package/dist/ui/settings-token.js

@@ -0,0 +1,54 @@
+// #1519 P1 (docs/design/ux-onboarding-walkthrough.md §5.2): the one bot-token field — the setup wizard, "New
+// connection" and a connection's "Replace token" use it. A password field (show/hide), Verify asks the platform who the
+// token belongs to (Telegram getMe, Discord /users/@me) and shows the bot's name before anything is written. The token
+// lives in this field's state only: never in storage, a URL, a label or the page's other state, and the server never
+// hands it back — afterwards a connection shows "Token set · @bot".
+import { html, useState } from "/assets/app-html.js";
+import { t } from "/assets/app-i18n.js";
+import { Icon } from "/assets/ui-icons.js";
+import { api } from "./settings-confirm.js";
+
+const tn = (k, ...v) => t(`settings.${k}`, ...v);
+
+/** Who this token is: { valid, username?, reason? } — one outbound check, the token sent once and not kept. */
+export async function verifyBotToken(platform, token) {
+  const res = await api("/api/settings/quickstart/probe", { method: "POST", body: JSON.stringify({ action: "verify", platform, token }) })
+    .catch(() => ({ ok: false, body: {} }));
+  // A Discord bot's invite and portal page come with it (#1519 P3).
+  if (res.ok && res.body && res.body.identity) return { ...res.body.identity, invite: res.body.invite_url || null, portal: res.body.portal_url || null };
+  return { valid: false, reason: (res.body && res.body.error) || tn("verifyFailed") };
+}
+
+/** A bot's name as it is addressed: @name, once. */
+export const botHandle = (username) => (username ? `@${String(username).replace(/^@/, "")}` : "");
+
+/**
+ * The field. props: id, platform, value, onInput(token) (the parent drops its verified identity on a change and moves
+ * its credential revision, so a Verify still on its way for the old value cannot land — #1529 review),
+ * identity ({ valid, username, reason } | null), busy (the field is locked meanwhile), onVerify(), hint.
+ */
+export function TokenField({ id, platform, value, onInput, identity, busy, onVerify, hint }) {
+  const [shown, setShown] = useState(false);
+  return html`<div class="field token-field"><label for=${id}>${tn("wizardToken")}</label>
+    <div class="token-row">
+      <input id=${id} type=${shown ? "text" : "password"} autocomplete="off" autocapitalize="off" spellcheck="false" disabled=${!!busy}
+        placeholder=${platform === "discord" ? "MTA…" : "123456:ABC-DEF…"} value=${value} onInput=${(e) => onInput(e.target.value.trim())} />
+      <button type="button" class="icon-btn" aria-pressed=${shown ? "true" : "false"} title=${shown ? tn("tokenHide") : tn("tokenShow")}
+        aria-label=${shown ? tn("tokenHide") : tn("tokenShow")} onClick=${() => setShown(!shown)}><${Icon} name="eye" size=${16} /></button>
+    </div>
+    <p class="note">${hint || (platform === "telegram" ? tn("wizardTokenTelegram") : tn("wizardTokenDiscord"))}</p>
+    <div class="dlg-inline-actions"><button type="button" class="btn btn-sm" disabled=${busy || !value} onClick=${onVerify}>${tn("wizardVerify")}</button>
+      ${identity ? html`<span class=${`feedback${identity.valid ? " ok" : " error"}`} role="status">${identity.valid
+        ? tn("tokenIsBot", botHandle(identity.username) || tn("verified")) : (identity.reason || tn("verifyFailed"))}</span>` : null}</div>
+  </div>`;
+}
+
+/** The generated env var a token is stored under, read-only with a copy button (the "Advanced" view). */
+export function TokenEnvNote({ name }) {
+  const [copied, setCopied] = useState(false);
+  if (!name) return null;
+  const copy = async () => { try { await navigator.clipboard.writeText(name); setCopied(true); } catch { /* the name is on screen */ } };
+  return html`<div class="field"><span>${tn("tokenEnv")}</span>
+    <div class="dlg-inline-actions"><code>${name}</code><button type="button" class="btn btn-sm btn-ghost" onClick=${copy}>${copied ? tn("copied") : tn("copy")}</button></div>
+    <p class="note">${tn("tokenStoredAs")}</p></div>`;
+}

package/dist/ui/settings-wizard.js

@@ -2,14 +2,16 @@
 // configuration and, when it finishes, writes the files (a write an admin may have to confirm, #1423) and hands over
 // to the ordinary Apply: the app's runner (settings-apply.js) posts the apply and watches its job, with the same
 // progress, deadline and restart recovery as every other change.
-import { html, useEffect, useState } from "/assets/app-html.js";
+import { html, useEffect, useRef, useState } from "/assets/app-html.js";
 import { t } from "/assets/app-i18n.js";
 import { useLease } from "/assets/app-ctx.js";
 import { Dialog } from "/assets/ui-dialog.js";
 import { api } from "./settings-confirm.js";
 import { startOperation } from "./settings-apply.js";
 import { BACKENDS, DEFAULT_SCHEMA, impactOf, toYaml } from "./settings-model.js";
-import { Select } from "./settings-dialogs.js";
+import { Drawer, Select } from "./settings-dialogs.js";
+import { botHandle, TokenEnvNote, TokenField, verifyBotToken } from "./settings-token.js";
+import { DiscordServerPicker } from "./settings-discord.js";
 
 const tn = (k, ...v) => t(`settings.${k}`, ...v);
 const STEPS = 4;
@@ -18,6 +20,10 @@ const post = (path, body) => api(path, { method: "POST", body: JSON.stringify(bo
 export function SetupWizard({ ctx, onClose }) {
   const lease = useLease("wizard");
   const [w, setW] = useState(null);
+  // The credential's revision (#1529 review): a token or platform change moves it, and a Verify, Detect or plan that
+  // began before is dropped when it lands — an answer about an old token never names, or plans for, a new one.
+  const rev = useRef(0);
+  const bump = () => { rev.current++; };
   const [busy, setBusy] = useState("");
   const [err, setErr] = useState("");
   useEffect(() => {
@@ -25,37 +31,51 @@ export function SetupWizard({ ctx, onClose }) {
       const env = await api("/api/settings/quickstart/environment").catch(() => null);
       if (!lease.current()) return;
       const e = (env && env.body) || { backends: [], channels: [], has_fleet: false };
-      setW({ step: 1, env: e, backend: (e.backends || [])[0] || "claude-code", working_directory: "", instance_name: "agent-1",
-        platform: "telegram", token: "", token_env: "AGEND_BOT_TOKEN", group_id: "", guild_id: "", general_channel_id: "", admin_user_id: "",
+      // #1519 P7: with agents already there, the bot is for one of them by default; a new agent gets a free name.
+      const agents = Array.isArray(e.agents) ? e.agents : [];
+      const names = new Set(agents.map((a) => a.name));
+      let n = 1; while (names.has(`agent-${n}`)) n++;
+      setW({ step: 1, env: e, backend: (e.backends || [])[0] || "claude-code", working_directory: "", instance_name: `agent-${n}`,
+        agent: agents.length ? "existing" : "new", existing_name: agents.length ? agents[0].name : "",
+        platform: "telegram", token: "", group_id: "", guild_id: "", general_channel_id: "", admin_user_id: "",
         identity: null, guilds: [], plan: null, offset: 0 });
     })();
   }, [lease]);
   if (!w) return html`<${Dialog} title=${tn("wizardTitle")} onClose=${onClose}><p class="note">…</p></${Dialog}>`;
-  const set = (k) => (v) => setW((x) => ({ ...x, [k]: v }));
+  // Every field the plan or a probe is about moves the revision (#1529 review r2): a plan or Detect that began before an
+  // edit — target, admin, backend, directory, name — is dropped when it lands, never committed or written over the edit.
+  const set = (k) => (v) => { bump(); setW((x) => ({ ...x, [k]: v })); };
+  // No token env: the plan generates one (#1519 P1: AGEND_<PLATFORM>_<ID>_TOKEN, unique) and the commit carries the plan's.
+  // An existing agent (#1519 P7) is named and nothing else: the server keeps its directory and backend.
   const input = () => ({
-    platform: w.platform, token_env: w.token_env, backend: w.backend, working_directory: w.working_directory, instance_name: w.instance_name,
+    platform: w.platform,
+    ...(w.agent === "existing" ? { instance_name: w.existing_name, existing_agent: true }
+      : { backend: w.backend, working_directory: w.working_directory, instance_name: w.instance_name }),
     group_id: w.group_id || undefined, guild_id: w.guild_id || undefined, general_channel_id: w.general_channel_id || undefined,
     admin_user_id: w.admin_user_id || undefined,
   });
 
   const verify = async () => {
+    const at = rev.current, token = w.token, platform = w.platform;
+    const live = () => lease.current() && rev.current === at;
     setBusy(tn("wizardVerifying")); setErr("");
-    const res = await post("/api/settings/quickstart/probe", { action: "verify", platform: w.platform, token: w.token });
-    if (!lease.current()) return;
-    const identity = (res.body && res.body.identity) || { valid: false };
+    const identity = await verifyBotToken(platform, token);
+    if (!live()) { if (lease.current()) setBusy(""); return; }
     let guilds = [];
-    if (identity.valid && w.platform === "discord") {
-      const g = await post("/api/settings/quickstart/probe", { action: "guilds", token: w.token });
-      if (!lease.current()) return;
+    if (identity.valid && platform === "discord") {
+      const g = await post("/api/settings/quickstart/probe", { action: "guilds", token });
+      if (!live()) { if (lease.current()) setBusy(""); return; }
       guilds = (g.body && g.body.guilds) || [];
     }
     setBusy("");
-    setW((x) => ({ ...x, identity, guilds }));
+    setW((x) => (x.token === token && x.platform === platform ? { ...x, identity, guilds } : x));
   };
   const detect = async () => {
+    const at = rev.current;
     setBusy(tn("wizardWaitingStart")); setErr("");
     const res = await post("/api/settings/quickstart/probe", { action: "await-telegram-start", token: w.token, offset: w.offset || 0 });
     if (!lease.current()) return;
+    if (rev.current !== at) { setBusy(""); return; }
     setBusy("");
     if (!res.ok) { setErr((res.body && res.body.error) || tn("applyFailed")); return; }
     if (res.body.found) setW((x) => ({ ...x, offset: res.body.offset, group_id: String(res.body.found.groupId), admin_user_id: String(res.body.found.userId) }));
@@ -63,14 +83,19 @@ export function SetupWizard({ ctx, onClose }) {
   };
   const next = async () => {
     setErr("");
-    if (w.step === 1) { if (!w.working_directory.startsWith("/")) { setErr(tn("wizardNeedDir")); return; } setW({ ...w, step: 2 }); return; }
+    if (w.step === 1) {
+      if (w.agent !== "existing" && !w.working_directory.startsWith("/")) { setErr(tn("wizardNeedDir")); return; }
+      setW({ ...w, step: 2 }); return;
+    }
     if (w.step === 2) { setW({ ...w, step: 3 }); return; }
     if (w.step === 3) {
       if (!w.identity || !w.identity.valid) { setErr(tn("wizardNeedVerify")); return; }
+      const at = rev.current;
       setBusy(tn("wizardPlanLoading"));
       const res = await post("/api/settings/quickstart/plan", input());
       if (!lease.current()) return;
       setBusy("");
+      if (rev.current !== at) return;
       if (!res.ok) { setErr((res.body && res.body.error) || tn("applyFailed")); return; }
       setW((x) => ({ ...x, plan: res.body, step: 4 }));
       return;
@@ -84,7 +109,9 @@ export function SetupWizard({ ctx, onClose }) {
  * commit's body until that write completes, then drops it.
    */
   const finish = () => {
-    const body = { ...input(), token: w.token };
+    // The plan's target, all of it (#1529 review): its connection id and its generated token env — the commit refuses
+    // either if it was taken since, instead of quietly picking another.
+    const body = { ...input(), channel_id: w.plan.channel_id, token_env: w.plan.token_env, token_env_generated: true, token: w.token };
     // It writes the connection and the first agent: it costs what a connection change does (the server's schema).
     const handed = startOperation([{ label: tn("wizardTitle"), impact: impactOf((ctx && ctx.schema) || DEFAULT_SCHEMA, "fleet.channels"),
       request: { method: "POST", url: "/api/settings/quickstart/commit", body, sensitive: true } }]);
@@ -94,28 +121,31 @@ export function SetupWizard({ ctx, onClose }) {
   };
 
   let body;
+  const agents = Array.isArray(w.env.agents) ? w.env.agents : [];
   if (w.step === 1) {
-    body = html`<div class="field"><label for="wz-be">${tn("wizardBackend")}</label>
+    const which = agents.length ? html`<div class="seg-inline" role="group" aria-label=${tn("wizardAgentWhich")}>
+        ${["existing", "new"].map((k) => html`<button key=${k} type="button" class=${`btn${w.agent === k ? " btn-primary" : ""}`} aria-pressed=${w.agent === k ? "true" : "false"}
+          onClick=${() => set("agent")(k)}>${k === "existing" ? tn("wizardAgentExisting") : tn("wizardAgentNew")}</button>`)}</div>` : null;
+    body = w.agent === "existing" ? html`${which}
+      <div class="field"><label for="wz-agent">${tn("wizardAgentPick")}</label>
+        <${Select} id="wz-agent" value=${w.existing_name} onChange=${set("existing_name")} options=${agents.map((a) => a.name)} />
+        <p class="note">${tn("wizardAgentExistingNote")}</p></div>` : html`${which}<div class="field"><label for="wz-be">${tn("wizardBackend")}</label>
         <${Select} id="wz-be" value=${w.backend} onChange=${set("backend")} options=${w.env.backends && w.env.backends.length ? w.env.backends : BACKENDS} />
         <p class="note">${w.env.backends && w.env.backends.length ? tn("wizardBackendFound", w.env.backends.join(", ")) : tn("wizardBackendNone")}</p></div>
       <div class="field"><label for="wz-wd">${tn("workingDir")}</label><input id="wz-wd" type="text" placeholder="/home/you/projects/app" value=${w.working_directory} onInput=${(e) => set("working_directory")(e.target.value.trim())} /></div>
-      <div class="field"><label for="wz-name">${tn("wizardAgentName")}</label><input id="wz-name" type="text" value=${w.instance_name} onInput=${(e) => set("instance_name")(e.target.value.trim())} /></div>`;
+      <div class="field"><label for="wz-name">${agents.length ? tn("wizardAgentNewName") : tn("wizardAgentName")}</label><input id="wz-name" type="text" value=${w.instance_name} onInput=${(e) => set("instance_name")(e.target.value.trim())} /></div>`;
   } else if (w.step === 2) {
     body = html`<div class="seg-inline" role="group" aria-label=${tn("wizardPlatform")}>
         ${["telegram", "discord"].map((p) => html`<button key=${p} type="button" class=${`btn${w.platform === p ? " btn-primary" : ""}`} aria-pressed=${w.platform === p ? "true" : "false"}
-          onClick=${() => setW({ ...w, platform: p, identity: null })}>${p === "telegram" ? "Telegram" : "Discord"}</button>`)}</div>
+          onClick=${() => { bump(); setW((x) => ({ ...x, platform: p, identity: null })); }}>${p === "telegram" ? "Telegram" : "Discord"}</button>`)}</div>
       <p class="note">${w.platform === "telegram" ? tn("wizardTelegramHint") : tn("wizardDiscordHint")}</p>`;
   } else if (w.step === 3) {
-    body = html`<div class="field"><label for="wz-token">${tn("wizardToken")}</label>
-        <input id="wz-token" type="password" autocomplete="new-password" placeholder="123456:ABC-DEF…" value=${w.token} onInput=${(e) => setW({ ...w, token: e.target.value.trim(), identity: null })} />
-        <p class="note">${w.platform === "telegram" ? tn("wizardTokenTelegram") : tn("wizardTokenDiscord")}</p></div>
-      <div class="field"><label for="wz-env">${tn("tokenEnv")}</label><input id="wz-env" type="text" value=${w.token_env} onInput=${(e) => set("token_env")(e.target.value.trim())} /></div>
-      <div class="dlg-inline-actions"><button type="button" class="btn btn-sm" disabled=${!!busy} onClick=${verify}>${tn("wizardVerify")}</button>
-        ${w.identity ? html`<span class=${`feedback${w.identity.valid ? "" : " error"}`} role="status">${w.identity.valid ? (w.identity.username || tn("verified")) : (w.identity.reason || tn("verifyFailed"))}</span>` : null}</div>
+    body = html`<${TokenField} id="wz-token" platform=${w.platform} value=${w.token} identity=${w.identity} busy=${!!busy}
+        onInput=${(v) => { bump(); setW((x) => ({ ...x, token: v, identity: null })); }} onVerify=${verify} />
       ${w.platform === "discord" ? html`
-        <div class="field"><label for="wz-guild">${tn("guildIdField")}</label><${Select} id="wz-guild" value=${w.guild_id} onChange=${set("guild_id")}
-          options=${["", ...w.guilds.map((g) => ({ value: g.id, label: `${g.name} (${g.id})` }))]} /></div>
-        <div class="field"><label for="wz-gen">${tn("wizardGeneralChannel")}</label><input id="wz-gen" type="text" value=${w.general_channel_id} onInput=${(e) => set("general_channel_id")(e.target.value.trim())} /></div>
+        <${DiscordServerPicker} idPrefix="wz" token=${w.identity && w.identity.valid ? w.token : ""} bot=${w.identity && botHandle(w.identity.username)}
+          invite=${w.identity && w.identity.invite} portal=${w.identity && w.identity.portal} guilds=${w.guilds} onGuilds=${(g) => setW((x) => ({ ...x, guilds: g }))}
+          guild=${w.guild_id} onGuild=${set("guild_id")} channel=${w.general_channel_id} onChannel=${set("general_channel_id")} />
         <div class="field"><label for="wz-user">${tn("wizardAdminUser")}</label><input id="wz-user" type="text" placeholder=${tn("discordUserPlaceholder")} value=${w.admin_user_id} onInput=${(e) => set("admin_user_id")(e.target.value.trim())} /></div>`
       : html`
         <div class="field"><label for="wz-group">${tn("groupIdField")}</label><input id="wz-group" type="text" placeholder="-1001234567890" value=${w.group_id} onInput=${(e) => set("group_id")(e.target.value.trim())} />
@@ -125,8 +155,12 @@ export function SetupWizard({ ctx, onClose }) {
   } else {
     body = !w.plan ? html`<p class="note">${tn("wizardPlanLoading")}</p>` : html`
       <p><strong>${tn("wizardWillWrite")}</strong></p>
-      <pre class="s-yaml">${toYaml({ channels: [w.plan.channel], instances: { [w.plan.instance.name]: { working_directory: w.plan.instance.working_directory, backend: w.plan.instance.backend } } })}</pre>
-      <p class="note">${tn("wizardEnvKeys", (w.plan.env_keys || []).join(", "))}</p>
+      <pre class="s-yaml">${toYaml({ channels: [w.plan.channel], instances: { [w.plan.instance.name]: { working_directory: w.plan.instance.working_directory, backend: w.plan.instance.backend, channel_id: w.plan.instance.channel_id,
+        ...(w.plan.instance.topic && w.plan.instance.topic.to != null ? { topic_id: w.plan.instance.topic.to } : {}) } } })}</pre>
+      ${w.plan.instance && w.plan.instance.existing ? html`<p class="note">${tn("wizardAgentExistingNote")}</p>` : null}
+      ${w.plan.instance && w.plan.instance.topic ? html`<p class="feedback warning">${w.plan.instance.topic.to == null
+        ? tn("wizardTopicNotCarried", w.plan.instance.topic.from) : tn("wizardTopicGeneral")}</p>` : null}
+      <${Drawer} title=${tn("advancedSection")}><${TokenEnvNote} name=${w.plan.token_env} /></${Drawer}>
       ${(w.plan.warnings || []).map((x, i) => html`<p key=${i} class="feedback warning">${x}</p>`)}`;
   }
   return html`<${Dialog} title=${tn("wizardTitle")} onClose=${onClose} wide=${true} busy=${busy === tn("wizardCommitting")}

package/dist/ui/shared/app-route.js

@@ -1,7 +1,7 @@
 // #1408 §3: the app's routes on the client. The same table as the server's classifier (src/web-shell-routes.ts;
 // a test runs both over one list of cases). Pure: no DOM, no history.
 
-export const FLEET_TABS = ["tasks", "schedules", "teams", "org", "config"];
+export const FLEET_TABS = ["tasks", "schedules", "teams", "org", "cache", "config"];
 export const SETTINGS_SECTIONS = ["agents", "bots", "classic", "general", "advanced"];
 const MAX_INSTANCE_NAME = 128;
 const PATH_SEPARATOR_OR_CONTROL = /[/\\\u0000-\u001f\u007f]/;

package/dist/ui/shared/app-shell.js

@@ -1,7 +1,7 @@
 // #1408 §2/§7: the app's frame — the sidebar (a drawer on a phone), the main area with its panel, the bottom tabs on a
 // phone, the connection line, toasts. Panels render their own header through <PanelHeader>, so every panel's title,
 // status and ⋯ actions sit in the same place.
-import { html, useEffect, useState } from "./app-html.js";
+import { html, useEffect, useLayoutEffect, useRef, useState } from "./app-html.js";
 import { Icon } from "./ui-icons.js";
 import { Toasts } from "./ui-toast.js";
 import { ConfirmHost } from "./ui-confirm.js";
@@ -11,6 +11,7 @@ import { navStore } from "./app-nav.js";
 import { chatPath, viewPath, settingsPath, routeKey, NEEDS_PATH } from "./app-route.js";
 import { SessionMenu } from "./app-session.js";
 import { ErrorState, Skeleton } from "./ui-states.js";
+import { InstanceNav, RosterNav } from "./instance-nav.js";
 
 /** Shell state shared with panels: the phone drawer, the collapsed sidebar, extensions a panel module adds. */
 export const shellStore = createStore({ drawer: false, collapsed: readCollapsed(), footer: [], keyboard: false, dialog: null, side: null });
@@ -25,6 +26,14 @@ export function setSideSection(Component) {
   return () => { if (shellStore.get().side === entry) shellStore.set({ side: null }); };
 }
 
+// The sidebar's instance list (alpha.2, N1): one component on every page. keepActiveInView lives with it.
+export { keepActiveInView } from "./instance-nav.js";
+
+/** #1519 P7: "New agent" from anywhere (the sidebar's +, an empty chat): the app registers what opens it. */
+let newInstanceOpener = null;
+export function setNewInstanceOpener(fn) { newInstanceOpener = fn; }
+export function requestNewInstance() { if (newInstanceOpener) newInstanceOpener(); }
+
 /** An app-level dialog (New instance): rendered by the shell until closed, whatever panel is showing. */
 export function showDialog(Component, props = {}) { shellStore.set({ dialog: { Component, props } }); }
 export function closeDialog() { shellStore.set({ dialog: null }); }
@@ -90,29 +99,6 @@ export function statusClass(i, exec, awaiting) {
 }
 export { statusLabel };
 
-function tooltip(i) {
-  const src = (s) => (s === "instance" || s === "classic" ? "configured" : s === "fleet-default" ? "fleet default" : s);
-  const model = i.model ? (i.model_source === "live" || i.model_source === "cli-default" || i.model_source === "unresolved" ? i.model : `${i.model} (${src(i.model_source)})`) : null;
-  const effort = i.effort ? `effort:${i.effort}${i.effort_source ? ` (${src(i.effort_source)})` : ""}` : null;
-  const ctx = i.context_pct != null ? `ctx:${Math.round(i.context_pct)}%` : null;
-  const cost = i.cost > 0 ? `$${i.cost.toFixed(2)}` : null;
-  return [i.name, i.backend, model, effort, ctx, cost, i.status].filter(Boolean).join(" · ");
-}
-
-function InstanceRow({ i, active, exec, awaiting }) {
-  const alias = typeof i.display_name === "string" && i.display_name.trim() && i.display_name.trim() !== i.name ? i.display_name.trim() : "";
-  const cls = statusClass(i, exec, awaiting);
-  // Two lines: the name (never shortened to make room for a badge, #1408 rough edge 6), then the alias and/or
-  // "needs you". Everything else is in the tooltip.
-  return html`<li><a class=${`inst${active ? " active" : ""}`} href=${chatPath(i.name)} title=${tooltip(i)} aria-current=${active ? "page" : undefined}
-      onClick=${closeDrawer}>
-    <span class=${`dot ${cls}`} aria-hidden="true"></span>
-    <span class="inst-text"><span class="inst-name">${i.name}</span>
-      ${alias || awaiting != null ? html`<span class="inst-sub">${alias ? html`<span class="inst-alias">${alias}</span>` : null}
-        ${awaiting != null ? html`<span class="badge-await" title=${awaiting || t("app.approxNote")}>${t("app.needsYou")}</span>` : null}</span>` : null}
-      <span class="sr-only">${statusLabel(i, exec, awaiting)}</span></span></a></li>`;
-}
-
 /** Sign in, and come back here afterwards (the sign-in page accepts only the app's own pages). */
 export function signInHref() {
   const here = typeof location !== "undefined" ? location.pathname + location.search : "/view";
@@ -122,7 +108,6 @@ export function signInHref() {
 function Sidebar({ route, onNewInstance, viewOnly }) {
   const app = useStore(appStore);
   const shell = useStore(shellStore);
-  const current = route && route.panel === "chat" ? route.instance : null;
   const on = (panel) => !!route && route.panel === panel;
   // A count badge is hidden at 0; its number is also in the link's accessible name.
   const navLink = (panel, href, icon, label, count = 0) => html`<a class=${`side-row${on(panel) ? " active" : ""}`} href=${href}
@@ -137,7 +122,7 @@ function Sidebar({ route, onNewInstance, viewOnly }) {
         <button type="button" class="icon-btn side-collapse" onClick=${toggleSidebar} aria-label=${narrow() ? t("app.closeMenu") : t("app.collapse")} title=${narrow() ? t("app.closeMenu") : t("app.collapse")} aria-controls="sidebar"><${Icon} name="sidebar" /></button>
       </div>
       <nav class="side-nav" aria-label=${t("app.menu")}>${navLink("view", "/view", "view", t("app.view"))}</nav>
-      ${shell.side ? html`<${shell.side.Component} />` : html`<div class="side-section"></div>`}
+      ${shell.side ? html`<${shell.side.Component} />` : html`<${ViewOnlyNav} route=${route} />`}
       <div class="side-foot">
         <${Prefs} />
         <a class="side-row" href=${signInHref()}><${Icon} name="user" /><span>${t("app.signIn")}</span></a>
@@ -148,19 +133,15 @@ function Sidebar({ route, onNewInstance, viewOnly }) {
     <div class="side-head">
       <a class="brand" href="/ui" onClick=${closeDrawer}>${t("app.brand")}</a>
       <button type="button" class="icon-btn side-collapse" onClick=${toggleSidebar} aria-label=${narrow() ? t("app.closeMenu") : t("app.collapse")} title=${narrow() ? t("app.closeMenu") : t("app.collapse")} aria-controls="sidebar"><${Icon} name="sidebar" /></button>
-      <button type="button" class="icon-btn" onClick=${onNewInstance} aria-label=${t("app.newInstance")} title=${t("app.newInstance")}><${Icon} name="edit" /></button>
+      <button type="button" class="icon-btn" onClick=${onNewInstance} aria-label=${t("app.newInstance")} title=${t("app.newInstance")}><${Icon} name="plus" /></button>
     </div>
     <nav class="side-nav" aria-label=${t("app.menu")}>
       ${navLink("needs", NEEDS_PATH, "inbox", t("app.needsNav"), needsCount)}
       ${navLink("fleet", "/ui/fleet", "fleet", t("app.fleet"))}
       ${navLink("view", "/view", "view", t("app.view"))}
     </nav>
-    ${shell.side ? html`<${shell.side.Component} />` : html`<div class="side-section" id="instanceList">
-      <h2 class="side-label">${t("app.instances")}</h2>
-      ${app.instances.length ? html`<ul class="inst-list">${app.instances.map(i => html`<${InstanceRow} key=${i.name} i=${i} active=${i.name === current}
-          exec=${app.exec[i.name]} awaiting=${Object.prototype.hasOwnProperty.call(app.awaiting, i.name) ? app.awaiting[i.name] : null} />`)}</ul>`
-        : html`<p class="side-empty">${t("app.noInstances")}</p>`}
-    </div>`}
+    ${shell.side ? html`<${shell.side.Component} />` : html`<${InstanceNav} route=${route} items=${app.instances} loaded=${app.ready !== false}
+        exec=${app.exec} awaiting=${app.awaiting} onPick=${closeDrawer} />`}
     <div class="side-foot">
       ${navLink("settings", settingsPath(), "settings", t("app.settings"))}
       ${shell.footer.map(({ key, Component }) => html`<${Component} key=${key} />`)}
@@ -170,6 +151,11 @@ function Sidebar({ route, onNewInstance, viewOnly }) {
   </aside>`;
 }
 
+/** The anonymous View reader's list: View's roster read (no status frames without a session), the same component. */
+function ViewOnlyNav({ route }) {
+  return html`<${RosterNav} route=${route} viewOnly=${true} onPick=${closeDrawer} />`;
+}
+
 function Prefs() {
   const [theme, setTheme] = useState(typeof AgendTheme !== "undefined" ? AgendTheme.get() : "system");
   const [l, setL] = useState(lang());
@@ -245,14 +231,16 @@ const mmss = (ms) => { const s = Math.max(0, Math.ceil(ms / 1000)); return `${Ma
 
 /**
  * #1423: Settings writes an admin has to confirm, from whichever panel made them (settings-confirm.js publishes them to
- * appStore.pendingChanges). What it asks, how to confirm it, the countdown, Withdraw — in any panel.
+ * appStore.pendingChanges). What it asks, how to confirm it, the countdown, Withdraw — in any panel: a card in the
+ * corner, except in Settings itself, which shows the same cards in its column, right under the operation (`inline`),
+ * so they never cover it (alpha.2 sweep).
  */
-function PendingChanges() {
+export function PendingChanges({ inline = false } = {}) {
   const { pendingChanges } = useStore(appStore);
   const list = pendingChanges || [];
   useTick(list.some(p => p.state === "pending"));
   if (!list.length) return null;
-  return html`<div class="pending-stack" role="region" aria-label=${t("app.pendingTitle")}>${list.map(p => html`<section key=${p.id} class=${`pending-card ${p.state}`} role="status">
+  return html`<div class=${`pending-stack${inline ? " inline" : ""}`} role="region" aria-label=${t("app.pendingTitle")}>${list.map(p => html`<section key=${p.id} class=${`pending-card ${p.state}`} role="status">
     <div class="pending-head"><${Icon} name=${p.state === "applied" ? "check" : p.state === "pending" || p.state === "applying" ? "clock" : "alert"} size=${16} />
       <strong>${t(`app.pending_${p.state}`)}</strong>
       ${p.state === "pending" ? html`<span class="pending-left">${t("app.pendingLeft", mmss(p.deadline - NOW()))}</span>` : null}
@@ -336,7 +324,7 @@ export function Shell({ panels, onNewInstance, viewOnly = false }) {
     </main>
     <${BottomTabs} route=${nav.route} viewOnly=${viewOnly} />
     ${shell.dialog ? html`<${shell.dialog.Component} ...${shell.dialog.props} onClose=${closeDialog} />` : null}
-    ${viewOnly ? null : html`<${PendingChanges} />`}
+    ${viewOnly || (nav.route && nav.route.panel === "settings") ? null : html`<${PendingChanges} />`}
     <${ConfirmHost} />
     <${Toasts} />
   </div>`;

package/dist/ui/shared/app-store.js

@@ -21,8 +21,9 @@ export function createStore(initial) {
 /** The app's store. `ready`: a status frame has arrived (before it, an unknown instance may just not be listed yet).
  *  `exec`: each instance's raw execution state (working / idle / stuck / null); `awaiting`: what it
  *  waits on at its terminal (text, "" when unknown), absent when it waits on nothing. `hydration`: a late catch-up
- *  (app-stream.js catchUp) — "catching" / "retrying" / "failed" / "ok"; `retryHydration` asks for it again. */
-export const appStore = createStore({ ready: false, instances: [], uptime: 0, exec: {}, awaiting: {}, connection: "connecting", needs: [],
+ *  (app-stream.js catchUp) — "catching" / "retrying" / "failed" / "ok"; `retryHydration` asks for it again.
+ *  `connections`: how many chat connections the fleet has (#1519 P7: 0 is web-only — the first-run card); null until known. */
+export const appStore = createStore({ ready: false, instances: [], uptime: 0, exec: {}, awaiting: {}, connection: "connecting", needs: [], connections: null,
   hydration: "none", retryHydration: null });
 
 /** Fold one status frame (stream or poll) into the store. */
@@ -34,7 +35,8 @@ export function applyStatus(d) {
     exec[i.name] = (i.execution_state !== undefined ? i.execution_state : i.state) ?? null;
     if (i.state === "awaiting_input") awaiting[i.name] = typeof i.interaction_summary === "string" ? i.interaction_summary : "";
   }
-  appStore.set({ ready: true, instances: d.instances, uptime: d.uptime ?? 0, exec, awaiting });
+  appStore.set({ ready: true, instances: d.instances, uptime: d.uptime ?? 0, exec, awaiting,
+    connections: typeof d.connections === "number" ? d.connections : null });
 }
 
 /** One "activity" event: an instance started or stopped working. */

package/dist/ui/shared/app-stream.js

@@ -15,7 +15,7 @@
 // older snapshot. A failed read is retried a few times with a growing delay, and then waits for the person (Retry);
 // the state is told as "hydration" events. Polls never overlap: a poll asked for while one runs follows it.
 
-const EVENTS = ["status", "message", "delivery", "deliveries", "prompt", "prompts", "prompt_resolved", "activity", "needs"];
+const EVENTS = ["status", "message", "delivery", "deliveries", "prompt", "prompts", "prompt_resolved", "activity", "needs", "reply_buttons"];
 const MAX_HELD = 1000;                    // live events held during one catch-up read; more → read again afterwards
 const RETRY_DELAYS = [1000, 2000, 4000];  // after the first failed catch-up read; then it waits for Retry
 const POLL_LIMIT_MS = 10000;              // a poll that has not answered by then counts as failed
@@ -83,6 +83,7 @@ export function createStream(opts) {
         if (typeof d.cursor === "string") state.cursor = d.cursor;
         if (Array.isArray(d.deliveries)) emit("deliveries", d.deliveries);
         if (Array.isArray(d.prompts)) emit("prompts", d.prompts);
+        if (Array.isArray(d.reply_buttons)) for (const u of d.reply_buttons) emit("reply_buttons", u);   // #1266
         if (Array.isArray(d.needs)) emit("needs", { items: d.needs });
         return true;
       } catch { return false; /* the next tick, or the catch-up's retry, tries again */ }