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

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

package/dist/ui/settings-strings.js

@@ -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}",
@@ -310,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.",
@@ -424,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: "目前版本",
@@ -447,7 +478,7 @@ register("settings", {
     wizardButton: "設定精靈",
     wizardTitle: "設定 AgEnD",
     wizardStep: "第 {0} 步，共 {1} 步",
-    wizardRerun: "已經有設定好的 fleet —— 完成後會取代使用相同 token 變數的那個連線。",
+    wizardRerun: "已經有設定好的 fleet —— 完成後會新增一個連線，不會取代任何既有的設定。",
     wizardBack: "上一步",
     wizardNext: "下一步",
     wizardFinish: "建立並啟動",
@@ -455,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 邀請到你的伺服器。",
@@ -489,7 +528,7 @@ register("settings", {
     restartFleetConfirm: "現在重新啟動 AgEnD？\n\n所有 agent 都會停止再啟動，進行中的工作會被中斷，面板會有最多約一分鐘無法連線。聊天頻道會收到一則通知。",
     restartFleetStarted: "AgEnD 重新啟動中 —— 此頁面會持續確認。",
     restartFleetBusy: "重啟中…",
-    restartFleetTitle: "AgEnD 重新啟動中…",
+    restartFleetTitle: "AgEnD 重新啟動中…", connStartingNow: "正在啟動新連線——不需要重新啟動…",
     restartFleetWaiting: "AgEnD 正在重新啟動。此頁面會持續確認，恢復後會告訴你 —— 不需要再按任何按鈕。",
     working: "執行中…",
     restartFleetRefused: "重新啟動被拒絕：{0}",
@@ -634,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>`;
+}