@songsid/agend 2.3.0-beta.2 → 2.3.0-beta.20

package/dist/ui/settings-catalog.js

@@ -0,0 +1,92 @@
+// #2072 part 3: what a backend or model field in Settings offers — the host's published availability (installed,
+// signed in, new enough: /ui/backends) and the model catalog of that backend for that instance's account (/ui/models).
+// Both answers are the server's cached ones; nothing here makes the server probe. A page asks once and reuses the answer
+// for a short while, so opening several dialogs costs one request each.
+import { useEffect, useState } from "/assets/app-html.js";
+
+const TTL_MS = 30_000;
+const cache = new Map();   // url → { at, value, pending }
+
+async function getJson(url) {
+  const res = await fetch(url, { credentials: "same-origin" });
+  if (!res.ok) throw new Error(String(res.status));
+  return res.json();
+}
+/** The answer for `url`, shared by every field on the page while it is fresh; null when it cannot be read. */
+function cached(url) {
+  const hit = cache.get(url), now = performance.now();
+  if (hit && (hit.pending || now - hit.at < TTL_MS)) return hit.pending ?? Promise.resolve(hit.value);
+  const pending = getJson(url).then((value) => { cache.set(url, { at: performance.now(), value, pending: null }); return value; })
+    .catch(() => { cache.delete(url); return null; });
+  cache.set(url, { at: now, value: null, pending });
+  return pending;
+}
+/**
+ * Drop every remembered answer. Only tests call it today: a page keeps an answer TTL_MS, so a sign-in or a newly
+ * cached catalog shows within that time, or at once on the next page load.
+ */
+export function forgetCatalogs() { cache.clear(); }
+
+function useAnswer(url) {
+  const [value, setValue] = useState(undefined);   // undefined: loading; null: unavailable
+  useEffect(() => {
+    if (!url) { setValue(null); return undefined; }
+    let live = true;
+    setValue(undefined);
+    cached(url).then((v) => { if (live) setValue(v); });
+    return () => { live = false; };
+  }, [url]);
+  return value;
+}
+
+/** The host's backends with their state ({ name, state, minVersion, … }), or null while loading or unavailable. */
+export function useBackendRows() {
+  const answer = useAnswer("/ui/backends");
+  return answer && Array.isArray(answer.backends) ? answer.backends : answer === undefined ? undefined : null;
+}
+
+/** The model catalog of `backend` for `instance` (its account) — [] when none is cached; undefined while loading. */
+export function useModelCatalog(backend, instance) {
+  const url = backend ? `/ui/models?backend=${encodeURIComponent(backend)}${instance ? `&instance=${encodeURIComponent(instance)}` : ""}` : null;
+  const answer = useAnswer(url);
+  if (answer === undefined) return undefined;
+  return answer && Array.isArray(answer.models) ? answer.models : [];
+}
+
+/** A state that keeps a backend from being chosen (shown, disabled, with why); "unknown" never does. */
+export const BLOCKING_STATES = ["not_installed", "not_signed_in", "too_old"];
+
+/**
+ * The backend select's options: every backend the page knows, in its order, each with what the host said about it.
+ * The current value is always selectable — a probe never disables what an agent already runs — and one the page does
+ * not know (a removed backend) stays first, as before.
+ */
+export function backendChoices(known, rows, value, words) {
+  const byName = new Map((rows || []).map((r) => [r.name, r]));
+  const choice = (name) => {
+    const row = byName.get(name), state = row ? row.state ?? (row.installed ? "usable" : row.unknown ? "unknown" : "not_installed") : null;
+    const blocked = !!state && BLOCKING_STATES.includes(state) && name !== value;
+    const note = state === "not_installed" ? words.notInstalled : state === "not_signed_in" ? words.notSignedIn
+      : state === "too_old" ? words.tooOld(row.minVersion ?? "?") : state === "unknown" && name !== value ? words.unchecked : "";
+    return { value: name, label: note ? `${name} — ${note}` : name, disabled: blocked };
+  };
+  const list = known.map(choice);
+  return known.includes(value) || !value ? list : [{ value, label: words.removed(value), disabled: false }, ...list];
+}
+
+/** The id of the "type another model" choice (never a model name: it has a space). */
+export const OTHER_MODEL = "\u0000other";
+
+/**
+ * The model select's options: the inherited choice (empty value), the current model first when the catalog does not
+ * list it (marked), the catalog, and "Other…" for a name the CLI does not list.
+ */
+export function modelChoices(catalog, value, words, inherit) {
+  const list = [];
+  if (inherit) list.push({ value: "", label: inherit });
+  const ids = new Set((catalog || []).map((m) => m.id));
+  if (value && !ids.has(value)) list.push({ value, label: `${value} — ${words.notListed}` });
+  for (const m of catalog || []) list.push({ value: m.id, label: m.description ? `${m.label || m.id} — ${m.description}` : (m.label || m.id) });
+  list.push({ value: OTHER_MODEL, label: words.other });
+  return list;
+}

package/dist/ui/settings-confirm.js

@@ -33,6 +33,10 @@ export async function api(path, opts = {}) {
 
 /** A request id we can follow: a non-empty string (the server's are 32 hex characters). */
 const usableId = (v) => typeof v === "string" && v.length > 0;
+/** #2170: a held request its own web-verified account confirmed (the server's answer says so): applying, no wait for chat. */
+export function selfConfirmed(view) {
+  return !!view && !!view.confirmation && view.confirmation.kind === "web";
+}
 /** The 202 that means "waiting for an admin", not "done". */
 export function isPendingResponse(res) {
   return !!res && res.status === 202 && !!res.body && res.body.result === "pending_confirmation" && !!res.body.pending_change
@@ -159,13 +163,14 @@ export async function attach() {
  * itself would have been: applied → { ok: true, body: what the write answered }, anything else → { ok: false } with
  * the reason. An accepted answer that cannot be read is { ok: false, ambiguous: true } (see isUnreadableAccept); a
  * network failure throws. Every other answer is returned as it is. `key` is the request's Idempotency-Key: pass the same one to
- * retry the same request. `onPending(id)` is told when it starts waiting.
+ * retry the same request. `onPending(id, view)` is told when it starts waiting — or, held and confirmed by its own
+ * web-verified account (selfConfirmed(view), #2170), applying.
  */
 export async function confirmedWrite(path, { method = "POST", body, key = newKey("w"), label, headers, onPending } = {}) {
   const res = await api(path, { method, headers: { ...(headers || {}), "Idempotency-Key": key }, body: body === undefined ? undefined : JSON.stringify(body) });
   if (isUnreadableAccept(res)) return { ok: false, status: 202, ambiguous: true, body: { error: "unreadable_confirmation_response" } };
   if (!isPendingResponse(res)) return res;
-  if (onPending) onPending(res.body.pending_change.id);
+  if (onPending) onPending(res.body.pending_change.id, res.body.pending_change);
   const final = await track(res.body.pending_change, label);
   return outcomeResponse(final);
 }

package/dist/ui/settings-dialogs.js

@@ -13,11 +13,13 @@ import { api, confirmedWrite, newKey } from "./settings-confirm.js";
 import { adminUserIdError, adminUserIdPattern, botHandle, TokenEnvNote, TokenField, verifyBotToken } from "./settings-token.js";
 import { DiscordServerPicker } from "./settings-discord.js";
 import { startOperation } from "./settings-apply.js";
+import "./settings-strings.js";   // its words, wherever a picker of this file is used (#2072: Fleet's create dialog too)
+import { backendChoices, modelChoices, OTHER_MODEL, useBackendRows, useModelCatalog } from "./settings-catalog.js";
 import {
   ACCESS_MODES, AGENT_FIELDS, AGENT_MODES, BOT_FIELDS, CH_TYPES, CLASSIC_FIELDS, HANG_TIMEOUT_DEFAULT_MINUTES, LOG_LEVELS, TOOL_PROGRESS, TOOL_SETS,
   VISIBILITY_MODES, accessConfirmations, agentForm, agentPatch, backendOptions, changedFields, channelId, channelsOf,
   chLabel, hasOwn, impactOf, nonNegative, nonNegativeInteger, positive, replyGuardSupported, sameValue, visibilityDefault,
-  webEchoIsGroup, worstImpact,
+  classicWebEchoEffective, worstImpact,
 } from "./settings-model.js";
 
 const tn = (k, ...v) => t(`settings.${k}`, ...v);
@@ -32,9 +34,36 @@ export function Select({ value, options, onChange, disabled, id, label }) {
   return html`<select id=${id} value=${value} disabled=${disabled} aria-label=${label} onChange=${(e) => onChange(e.target.value)}>
     ${opts.map((o) => html`<option key=${o.value} value=${o.value}>${o.label}</option>`)}</select>`;
 }
+/**
+ * #2072: a backend field shows every backend with what this host says about it — one it cannot run is disabled with
+ * why (not installed, not signed in, too old); one not checked yet stays selectable; the current value always can be.
+ */
 export function BackendSelect({ value, onChange, disabled, id }) {
-  return html`<${Select} id=${id} value=${value} disabled=${disabled} onChange=${onChange}
-    options=${backendOptions(value).map((o) => (o.unavailable ? { value: o.value, label: tn("backendUnavailable", o.value) } : o))} />`;
+  const rows = useBackendRows();
+  const known = backendOptions(value).filter((o) => !o.unavailable).map((o) => o.value);
+  const opts = backendChoices(known, rows || [], value, {
+    notInstalled: tn("backendNotInstalled"), notSignedIn: tn("backendNotSignedIn"), tooOld: (v) => tn("backendTooOld", v),
+    unchecked: tn("backendUnchecked"), removed: (v) => tn("backendUnavailable", v),
+  });
+  return html`<select id=${id} value=${value} disabled=${disabled} onChange=${(e) => onChange(e.target.value)}>
+    ${opts.map((o) => html`<option key=${o.value} value=${o.value} disabled=${o.disabled}>${o.label}</option>`)}</select>`;
+}
+/**
+ * #2072: a model field is a list — that backend's models for this account (cached; never a probe), the current one
+ * first and marked when the CLI does not list it, and "Other…" for a name it does not list (a text box opens with
+ * the current value in it: choosing "Other…" alone changes nothing — emptying the box is what inherits, #2098 review).
+ * `inherit`: the label of the empty choice (inherit / none), or omit it when the field has none.
+ */
+export function ModelSelect({ value, onChange, disabled, id, backend, instance, inherit }) {
+  const catalog = useModelCatalog(backend, instance);
+  const [typing, setTyping] = useState(false);
+  const opts = modelChoices(catalog || [], value, { notListed: tn("modelNotListed"), other: tn("modelOther") }, inherit);
+  return html`<div class="model-pick">
+    <select id=${id} value=${typing ? OTHER_MODEL : value} disabled=${disabled}
+      onChange=${(e) => { const v = e.target.value; if (v === OTHER_MODEL) setTyping(true); else { setTyping(false); onChange(v); } }}>
+      ${opts.map((o) => html`<option key=${o.value} value=${o.value}>${o.label}</option>`)}</select>
+    ${typing ? html`<input type="text" aria-label=${tn("modelOtherLabel")} placeholder=${tn("modelOtherPlaceholder")} disabled=${disabled}
+      value=${value} onInput=${(e) => onChange(e.target.value)} />` : null}</div>`;
 }
 export function Impact({ schema, field }) { return html`<span class="impact">${impactText(impactOf(schema, field))}</span>`; }
 export function Label({ text, schema, field, htmlFor }) {
@@ -228,7 +257,8 @@ export function AgentDialog({ name, inst, ctx, onClose }) {
           <input id="ag-dn" type="text" placeholder=${name} disabled=${f.inherit.display_name} value=${shown("display_name", f.display_name, defaults.display_name || "")} onInput=${(e) => set("display_name")(e.target.value)} /></${Override}></div>
       <div class="field">${L(tn("description"), "instance.description", "ag-desc")}<input id="ag-desc" type="text" value=${f.description} onInput=${(e) => set("description")(e.target.value)} /></div>
       <div class="field">${L(tn("backend"), "instance.backend", "ag-be")}<${BackendSelect} id="ag-be" value=${f.backend} onChange=${set("backend")} /></div>
-      <div class="field">${L(tn("model"), "instance.model", "ag-model")}<input id="ag-model" type="text" placeholder=${tn("inheritPlaceholder")} value=${f.model} onInput=${(e) => set("model")(e.target.value)} /></div>
+      <div class="field">${L(tn("model"), "instance.model", "ag-model")}<${ModelSelect} id="ag-model" value=${f.model} onChange=${set("model")}
+        backend=${f.backend || defaults.backend || "claude-code"} instance=${name} inherit=${tn("inheritPlaceholder")} /></div>
     </div>
     <div class="field">${L(tn("workingDir"), "instance.working_directory", "ag-wd")}<input id="ag-wd" type="text" value=${f.working_directory} onInput=${(e) => set("working_directory")(e.target.value)} /></div>
     <div class="field">${L(`${tn("autoPause")} (${tn("minutes")})`, "instance.auto_pause_after", "ag-auto")}
@@ -264,8 +294,8 @@ export function AgentDialog({ name, inst, ctx, onClose }) {
               onChange=${(e) => set("lightweight")(e.target.checked)} /><span>${tn("lightweight")}</span></label></${Override}></div>
         <div class="field">${L(tn("modelFailover"), "instance.model_failover", "ag-fo")}
           <${Override} inherit=${f.inherit.model_failover} onInherit=${setInherit("model_failover")}>
-            <input id="ag-fo" type="text" placeholder="e.g. sonnet" disabled=${f.inherit.model_failover}
-              value=${shown("model_failover", f.model_failover, (defaults.model_failover && defaults.model_failover[0]) || "")} onInput=${(e) => set("model_failover")(e.target.value)} /></${Override}>
+            <${ModelSelect} id="ag-fo" disabled=${f.inherit.model_failover} backend=${f.backend || defaults.backend || "claude-code"} instance=${name} inherit=${tn("modelNone")}
+              value=${shown("model_failover", f.model_failover, (defaults.model_failover && defaults.model_failover[0]) || "")} onChange=${set("model_failover")} /></${Override}>
           <${Feedback} warning=${failoverWarn} /></div>
       </div>
       <div class="field">${L(tn("systemPrompt"), "instance.systemPrompt", "ag-sys")}<input id="ag-sys" type="text" placeholder="e.g. file:prompts/dev.md" value=${f.systemPrompt} onInput=${(e) => set("systemPrompt")(e.target.value)} /></div>
@@ -557,7 +587,7 @@ export function ClassicDialog({ room, ctx, onClose }) {
     backend: c.backend || inherited.backend, model: c.model || "",
     auto_pause_after: String(c.auto_pause_after ?? inherited.auto_pause_after), tool_progress: c.tool_progress ?? inherited.tool_progress,
     reply_completion_guard: c.reply_completion_guard ?? inherited.reply_completion_guard,
-    collab: !!c.collab, web_echo: !!c.web_echo, context_lines: String(c.context_lines ?? cd.context_lines ?? 5),
+    collab: !!c.collab, web_echo: classicWebEchoEffective(c, fleet), context_lines: String(c.context_lines ?? cd.context_lines ?? 5),
     inherit: { auto_pause_after: !hasOwn(c, "auto_pause_after"), tool_progress: !hasOwn(c, "tool_progress"), reply_completion_guard: !hasOwn(c, "reply_completion_guard") },
   }));
   const set = (k) => (v) => setF((x) => ({ ...x, [k]: v }));
@@ -580,12 +610,9 @@ export function ClassicDialog({ room, ctx, onClose }) {
       auto_pause_after: hasOwn(c, "auto_pause_after") ? c.auto_pause_after : null,
       tool_progress: hasOwn(c, "tool_progress") ? c.tool_progress : null,
       reply_completion_guard: hasOwn(c, "reply_completion_guard") ? c.reply_completion_guard : null,
-      collab: !!c.collab, context_lines: c.context_lines ?? cd.context_lines ?? 5, web_echo: !!c.web_echo,
+      collab: !!c.collab, context_lines: c.context_lines ?? cd.context_lines ?? 5, web_echo: classicWebEchoEffective(c, fleet),
     });
     if (!Object.keys(patch).length) { onClose(); return; }
-    // #1320: turning web echo on for a group posts every web message where all its members can read it.
-    if (patch.web_echo === true && !c.web_echo && webEchoIsGroup(c.channelId)
-      && !(await ask(tn("webEchoGroupConfirm"), { confirmLabel: tn("webEchoEnable") }))) return;
     if (!lease.current()) return;
     ctx.stageClassic(c, patch);
     onClose();
@@ -594,7 +621,8 @@ export function ClassicDialog({ room, ctx, onClose }) {
   return html`<${EditDialog} title=${c.name || c.instanceName} subtitle=${`ID: ${c.instanceName} · ${tn(`exec_${runtime.execution}`)}`} onClose=${onClose} onStage=${stage} ready=${ready} impacts=${CLASSIC_FIELDS} schema=${schema}>
     <div class="grid2">
       <div class="field">${L(tn("backend"), "classic.backend", "cl-be")}<${BackendSelect} id="cl-be" value=${f.backend} onChange=${set("backend")} /></div>
-      <div class="field">${L(tn("model"), "classic.model", "cl-model")}<input id="cl-model" type="text" placeholder=${inherited.model || tn("inheritPlaceholder")} value=${f.model} onInput=${(e) => set("model")(e.target.value)} /></div>
+      <div class="field">${L(tn("model"), "classic.model", "cl-model")}<${ModelSelect} id="cl-model" value=${f.model} onChange=${set("model")}
+        backend=${f.backend} instance=${c.instanceName} inherit=${inherited.model ? tn("inheritValue", inherited.model) : tn("inheritPlaceholder")} /></div>
       <div class="field">${L(`${tn("autoPause")} (${tn("minutes")})`, "classic.auto_pause_after", "cl-auto")}
         <${Override} inherit=${f.inherit.auto_pause_after} onInherit=${setInherit("auto_pause_after")}>
           <input id="cl-auto" type="number" min="0" step="1" class=${errors.auto ? "invalid" : ""} disabled=${f.inherit.auto_pause_after}

package/dist/ui/settings-effects.js

@@ -4,10 +4,11 @@ import { register, t } from "/assets/app-i18n.js";
 import { appStore, useStore } from "/assets/app-store.js";
 import { confirmDialog } from "/assets/ui-confirm.js";
 import { OwnerEffects } from "./settings-owner-effects.js";
+import { CardTitle } from "./settings-learn.js";
 
 register("effectSettings", {
   en: {
-    title: "Effects", lead: "Manage effect files and save selections for a chat. Saving replaces that chat’s parameters with the values below.", folder: "Upload an effect folder", files: "Choose effect.json and worker.js, with optional raster assets. Up to 1 MiB after processing.",
+    title: "Effects", lead: "Your effect files, and which one a chat uses.", folder: "Upload an effect folder", files: "effect.json + worker.js (and pictures), up to 1 MiB.",
     inUse: "This effect is still in use and cannot be deleted.", quota: "Your library reached its 10-effect or 8 MiB limit. Delete unused copies first.", rateLimited: "Too many changes. Wait a moment, then try again.",
     loading: "Loading effects…", retry: "Reload library", empty: "No effects in your library.", failed: "Couldn't load the library. Try again.", actionFailed: "Couldn't save this change. Try again.", savedRefresh: "Saved. Reload the library to see the result.",
     uploadFailed: "Couldn't upload this folder. Check its files and size, then try again.", public: "Effect management isn't available on a temporary public link.", readOnly: "Read-only session: sign in as an admin to change effects.",
@@ -16,7 +17,7 @@ register("effectSettings", {
     fps: "Host FPS p50 / p10", tasks: "Host long task p95", noTasks: "Not observed", standard: "Standard device", constrained: "Constrained device", params: "Parameters", badParams: "Check the parameter values.", more: "Show more", count: "{0} effects", one: "1 effect", profileFailed: "Couldn't read profile history. Try again.",
   },
   "zh-TW": {
-    title: "效果", lead: "管理效果檔案，並儲存聊天的效果選擇。儲存時會以下方數值取代該聊天的效果參數。", folder: "上傳效果資料夾", files: "選擇 effect.json、worker.js，以及可選的點陣圖素材；處理後最多 1 MiB。",
+    title: "效果", lead: "你的效果檔案，以及每個聊天使用哪一個。", folder: "上傳效果資料夾", files: "effect.json + worker.js（可加圖片），最多 1 MiB。",
     inUse: "這個效果仍在使用中，無法刪除。", quota: "你的程式庫已達 10 個效果或 8 MiB 上限，請先刪除未使用的副本。", rateLimited: "變更太頻繁，請稍候再試。",
     loading: "正在載入效果…", retry: "重新載入程式庫", empty: "程式庫中還沒有效果。", failed: "無法載入程式庫，請重試。", actionFailed: "無法儲存變更，請重試。", savedRefresh: "已儲存，請重新載入程式庫查看結果。",
     uploadFailed: "無法上傳這個資料夾，請檢查檔案與大小後重試。", public: "臨時公開連結不提供效果管理。", readOnly: "目前為唯讀登入，請以管理員身分登入才能修改效果。",
@@ -180,7 +181,7 @@ export function EffectsCard() {
     if (!current(op.seq)) return; finish(op.seq);
     if (yes) await change(`/ui/effects/${id}`, undefined, "DELETE");
   };
-  return html`<section class="card s-appearance s-effects"><h3>${tn("title")}</h3><p class="sub">${tn("lead")}</p>
+  return html`<section class="card s-appearance s-effects"><${CardTitle} title=${tn("title")} topic="effects" /><p class="sub">${tn("lead")}</p>
     <div class="s-fx-actions"><button type="button" class="btn" disabled=${busy} onClick=${reload}>${tn("retry")}</button>
       ${view?.canWrite ? html`<button class="btn s-fx-choose" type="button" disabled=${busy} onClick=${() => uploadInput.current?.click()}>${tn("folder")}</button><input ref=${uploadInput} class="offscreen s-fx-upload" aria-label=${tn("folder")} tabindex="-1" type="file" webkitdirectory=${true} directory=${true} multiple disabled=${busy} onChange=${upload} />` : null}</div>
     ${busy ? html`<p class="sub" role="status">${tn("loading")}</p>` : null}${error ? html`<p class="err" role="status">${error}</p>` : null}${message ? html`<p class="sub" role="status">${message}</p>` : null}

package/dist/ui/settings-guests.js

@@ -0,0 +1,117 @@
+// #1920 phase 3 (P3b-2): Settings → Web → Guests — guest sign-in for people who are not admins. The switches (guest
+// sign-in, guests may chat), the agents an open connection's guests may reach, and every guest account: who, on which
+// platform, what it reaches now, its sessions and devices, with Sign out (at once) and Narrow (staged with the rest).
+// Changes go through Review changes → Apply like every Settings edit: one that widens what guests reach waits for a
+// fleet admin's confirmation (the server's settings-change.ts), one that narrows it applies at once.
+import { html, useEffect, useMemo, useState } from "/assets/app-html.js";
+import { t } from "/assets/app-i18n.js";
+import { toast } from "/assets/ui-toast.js";
+import { confirmDialog } from "/assets/ui-confirm.js";
+import { api } from "./settings-confirm.js";
+import "./settings-strings.js";
+
+const tn = (k, ...v) => t(`settings.${k}`, ...v);
+const PLATFORMS = { discord: "Discord", telegram: "Telegram" };
+const own = (o, k) => !!o && Object.prototype.hasOwnProperty.call(o, k);
+const copyLists = (m) => { const out = {}; for (const [k, v] of Object.entries(m || {})) if (Array.isArray(v)) out[k] = [...v]; return out; };
+const sameList = (a, b) => (a || []).length === (b || []).length && (a || []).every((n) => (b || []).includes(n));
+const accountKey = (g) => `${g.adapterId}:${g.userId}`;
+
+/** What changed against the configuration, as the PUT /api/settings/fleet/web body's `guests` (null: nothing). */
+export function guestsBody(original, f) {
+  const out = {};
+  if (f.enabled !== original.enabled) out.enabled = f.enabled ? true : null;          // off is the default
+  if (f.chat !== original.chat) out.chat = f.chat ? null : false;                     // on is the default
+  for (const key of ["open_instances", "narrow"]) {
+    const was = original[key], now = f[key], diff = {};
+    for (const k of new Set([...Object.keys(was), ...Object.keys(now)])) {
+      const a = own(was, k) ? was[k] : undefined, b = own(now, k) ? now[k] : undefined;
+      if (a === undefined && b === undefined) continue;
+      if (a !== undefined && b !== undefined && sameList(a, b)) continue;
+      // open_instances: none named = the entry leaves. narrow: undefined = lifted; [] = narrowed to nothing.
+      diff[k] = b === undefined || (key === "open_instances" && !b.length) ? null : [...b];
+    }
+    if (Object.keys(diff).length) out[key] = diff;
+  }
+  return Object.keys(out).length ? out : null;
+}
+
+/** `away`: narrowed names it no longer reaches — listed (marked) only so they can be unticked; unticked, they leave. */
+function Names({ id, all, value, onChange, away = new Set() }) {
+  const chosen = new Set(value || []);
+  return html`<div class="guest-names" id=${id} role="group">${all.map((n) => html`<label key=${n} class=${`check guest-name${away.has(n) ? " guest-away" : ""}`}>
+    <input type="checkbox" checked=${chosen.has(n)} onChange=${(e) => { const s = new Set(chosen); if (e.target.checked) s.add(n); else s.delete(n); onChange(all.filter((x) => s.has(x))); }} />
+    <span>${n}${away.has(n) ? html` <span class="note">${tn("guestNotReachable")}</span>` : null}</span></label>`)}</div>`;
+}
+
+export function GuestsCard({ ctx, staged, disabled = false }) {
+  const g = (ctx.fleet.web && ctx.fleet.web.guests) || {};
+  const original = useMemo(() => ({ enabled: g.enabled === true, chat: g.chat !== false, open_instances: copyLists(g.open_instances), narrow: copyLists(g.narrow) }), []);
+  const [f, setF] = useState(() => ({ ...original, open_instances: copyLists(original.open_instances), narrow: copyLists(original.narrow) }));
+  const [overview, setOverview] = useState(null), [failed, setFailed] = useState(false), [narrowing, setNarrowing] = useState(null), [msg, setMsg] = useState(null);
+  const load = async () => {
+    let r = null;
+    try { r = await api("/api/settings/guests"); } catch { r = null; }
+    if (r && r.ok && r.body) { setOverview(r.body); setFailed(false); } else setFailed(true);
+  };
+  useEffect(() => { load(); }, []);
+  const set = (patch) => setF((x) => ({ ...x, ...patch }));
+  const setList = (key, k, list) => setF((x) => { const m = { ...x[key] }; if (list === undefined) delete m[k]; else m[k] = list; return { ...x, [key]: m }; });
+  const review = () => {
+    const body = guestsBody(original, f);
+    if (body) ctx.stage("guests", { label: tn("guestsTitle"), impact: "now", request: { method: "PUT", url: "/api/settings/fleet/web", body: { guests: body } } });
+    else if (staged.has("guests")) ctx.unstage("guests");
+    setMsg(tn("readyApply"));
+  };
+  const signOut = async (guest) => {
+    const yes = await confirmDialog({ title: tn("guestSignOutTitle"), message: tn("guestSignOutConfirm", guest.name), confirmLabel: tn("guestSignOut"), danger: true });
+    if (!yes) return;
+    let r = null;
+    try { r = await api("/api/settings/guests/revoke", { method: "POST", body: JSON.stringify({ adapterId: guest.adapterId, userId: guest.userId }) }); } catch { r = null; }
+    if (r && r.ok) { toast(tn(r.body && r.body.durable === false ? "guestSignedOutNotDurable" : "guestSignedOut", guest.name)); load(); }
+    else toast(tn("guestSignOutFailed"), false);
+  };
+  const instances = (overview && overview.instances) || [];
+  const open = ((overview && overview.connections) || []).filter((c) => c.mode === "open");
+  const guests = (overview && overview.guests) || [];
+  const when = (ms) => (typeof ms === "number" ? tn("guestLastActive", new Date(ms).toLocaleString()) : tn("guestNotSignedIn"));
+  return html`<section class="card s-guests"><h3>${tn("guestsTitle")}</h3>
+    <p class="note">${tn("guestsHint")}</p>
+    <fieldset class="s-guest-fields" disabled=${disabled}>
+      <label class="check"><input id="guestsEnabled" type="checkbox" checked=${f.enabled} onChange=${(e) => set({ enabled: e.target.checked })} /><span>${tn("guestsEnabled")}</span></label>
+      <p class="note">${tn("guestsEnabledHint")}</p>
+      <label class="check"><input id="guestsChat" type="checkbox" checked=${f.chat} onChange=${(e) => set({ chat: e.target.checked })} /><span>${tn("guestsChat")}</span></label>
+      <p class="note">${tn("guestsChatHint")}</p>
+      ${open.map((c) => html`<div key=${c.id} class="field guest-open"><span class="label">${tn("guestsOpenFor", c.id, PLATFORMS[c.type] || c.type)}</span>
+        <p class="note">${tn("guestsOpenHint")}</p>
+        <${Names} id=${`guestsOpen-${c.id}`} all=${instances} value=${own(f.open_instances, c.id) ? f.open_instances[c.id] : []} onChange=${(list) => setList("open_instances", c.id, list)} /></div>`)}
+      <h4>${tn("guestsList")}</h4>
+      ${failed ? html`<p class="note" role="status">${tn("guestsLoadFailed")} <button type="button" class="btn btn-sm" onClick=${load}>${t("app.retry")}</button></p>`
+        : !overview ? html`<p class="note">${t("app.loading")}</p>`
+        : !guests.length ? html`<p class="note" id="guestsNone">${tn("guestsNone")}</p>`
+        : html`<ul class="guest-list">${guests.map((guest) => {
+          const k = accountKey(guest), narrowed = own(f.narrow, k) ? f.narrow[k] : undefined;
+          return html`<li key=${k} class="guest-row" data-account=${k}>
+            <div class="guest-who"><strong>${guest.name}</strong> <span class="note">${PLATFORMS[guest.platform] || guest.platform} · ${guest.userId}</span></div>
+            <div class="note guest-facts">${tn("guestFacts", guest.scope.length, guest.sessions, guest.devices)} · ${when(guest.lastSeen)}</div>
+            <div class="note guest-narrow">${narrowed === undefined ? tn("guestNotNarrowed") : tn("guestNarrowedTo", narrowed.length ? narrowed.join(", ") : tn("guestNothing"))}</div>
+            <div class="guest-actions">
+              <button type="button" class="btn btn-sm" aria-expanded=${narrowing === k ? "true" : "false"} onClick=${() => setNarrowing(narrowing === k ? null : k)}>${tn("guestNarrow")}</button>
+              ${narrowed !== undefined ? html`<button type="button" class="btn btn-sm" onClick=${() => setList("narrow", k, undefined)}>${tn("guestNarrowLift")}</button>` : null}
+              ${guest.sessions || guest.devices ? html`<button type="button" class="btn btn-sm btn-danger" onClick=${() => signOut(guest)}>${tn("guestSignOut")}</button>` : null}
+            </div>
+            ${narrowing === k ? (() => {
+              // #2104 review: only what this account can reach (narrowing never widens); a narrowed name it no longer
+              // reaches is listed to be unticked, marked.
+              const reach = guest.reach || guest.scope, away = new Set((narrowed || []).filter((n) => !reach.includes(n)));
+              return html`<div class="guest-narrow-edit"><p class="note">${tn("guestNarrowHint")}</p>
+                ${reach.length || away.size ? html`<${Names} id=${`guestNarrow-${k}`} all=${[...reach, ...away]} away=${away} value=${narrowed === undefined ? guest.scope : narrowed} onChange=${(list) => setList("narrow", k, list)} />`
+                  : html`<p class="note">${tn("guestReachesNothing")}</p>`}</div>`;
+            })() : null}
+          </li>`;
+        })}</ul>`}
+    </fieldset>
+    <div class="save-row"><button type="button" class="btn btn-primary" id="guestsReview" disabled=${disabled} onClick=${review}>${tn("guestsReview")}</button>
+      ${msg ? html`<span class="note" role="status">${msg}</span>` : null}</div>
+  </section>`;
+}

package/dist/ui/settings-learn.js

@@ -0,0 +1,25 @@
+// #2056 B: a card title with a small "?" that opens the card's section of the docs, so Settings → Web appearance
+// keeps one short line per control and the long explanations live in docs/web-dashboard(.zh-TW).md.
+import { html } from "/assets/app-html.js";
+import { lang, t } from "/assets/app-i18n.js";
+import "./settings-strings.js";
+
+/**
+ * #2056 B: where each card's long explanation lives — a heading of docs/web-dashboard(.zh-TW).md on GitHub, so the
+ * page keeps one short line per control and a small "?" for the rest.
+ */
+const DOCS = { en: "https://github.com/songsid/AgEnD/blob/main/docs/web-dashboard.md", "zh-TW": "https://github.com/songsid/AgEnD/blob/main/docs/web-dashboard.zh-TW.md" };
+export const LEARN_ANCHORS = {
+  colors: ["identity-colours", "識別色"], css: ["custom-css-settings--web-appearance", "自訂-css設定--網頁外觀"], themes: ["agents-themes", "agent-的主題"],
+  cards: ["identity-cards", "身分卡"], limits: ["card-upload-limits", "身分卡上傳限制"], widgets: ["widgets", "小工具"], mods: ["mods", "mod"],
+  effects: ["effects", "效果"], restore: ["restore-defaults", "還原預設值"],
+};
+export function learnHref(topic, language = lang()) {
+  const zh = language === "zh-TW";
+  return `${DOCS[zh ? "zh-TW" : "en"]}#${encodeURIComponent(LEARN_ANCHORS[topic][zh ? 1 : 0])}`;
+}
+/** A card title with its "?" link to the docs (a new tab; the page itself never fetches anything). */
+export function CardTitle({ title, topic }) {
+  return html`<h3 class="s-ap-title"><span>${title}</span>${topic ? html`<a class="s-learn" href=${learnHref(topic)} target="_blank" rel="noopener noreferrer"
+    aria-label=${t("settings.learnMore", title)} title=${t("settings.learnMore", title)}>?</a>` : null}</h3>`;
+}

package/dist/ui/settings-model.js

@@ -97,15 +97,20 @@ export function effectiveSummary(live, config, fleetDefaults, classicDefaults) {
   return { backend, model, effort };
 }
 
-/** Group by first tag, "Other" last; within a group Running → Paused → Crashed → Stopped, then by name. */
-export function groupAgents(instances, live, filter) {
+/**
+ * Group by `groupFor(name)` — #2172: the sidebar's rule (instance-nav groupOf: its first team, else its first tag); the
+ * first tag when not given — teams first, then tags, "Other" last; within a group Running → Paused → Crashed → Stopped,
+ * then by name. `labelOf(group)` sorts by what the heading says.
+ */
+export function groupAgents(instances, live, filter, groupFor = (n) => groupOf(instances[n]), labelOf = (g) => g) {
   const needle = String(filter || "").trim().toLowerCase();
   let names = Object.keys(instances || {});
   if (needle) names = names.filter((n) => n.toLowerCase().includes(needle) || shortName(n, instances[n]).toLowerCase().includes(needle));
   const groups = {};
-  for (const n of names) (groups[groupOf(instances[n])] ??= []).push(n);
+  for (const n of names) (groups[groupFor(n)] ??= []).push(n);
   const order = (n) => STATUS_ORDER[(live[n] && live[n].status) || "stopped"] ?? 9;
-  return Object.keys(groups).sort((a, b) => (a === "Other" ? 1 : b === "Other" ? -1 : a.localeCompare(b)))
+  const team = (g) => g.charCodeAt(0) < 32;                     // a team's key (instance-nav TEAM_GROUP)
+  return Object.keys(groups).sort((a, b) => (a === "Other" ? 1 : b === "Other" ? -1 : team(a) !== team(b) ? (team(a) ? -1 : 1) : labelOf(a).localeCompare(labelOf(b))))
     .map((g) => ({ group: g, names: groups[g].sort((a, b) => order(a) - order(b) || a.localeCompare(b)) }));
 }
 
@@ -222,8 +227,12 @@ export function accessConfirmations(previousAccess, nextMode, nextUsers) {
   return out;
 }
 
-/** #1320: only a short positive numeric id is a Telegram private chat; Discord snowflakes and negative ids are groups. */
-export const webEchoIsGroup = (channelIdValue) => !/^\d{1,12}$/.test(String(channelIdValue || ""));
+/**
+ * #2054: whether a ClassicBot room copies web chat, as the fleet decides it (ClassicChannelManager's load +
+ * classicWebEchoOn): an absent `web_echo` follows the fleet-wide `web.echo_to_channel` (default on); any other value
+ * echoes only when it is `true` (a `null`, `0` or string reads as off, as the manager reads it).
+ */
+export const classicWebEchoEffective = (room, fleet) => (room?.web_echo === undefined ? fleet?.web?.echo_to_channel !== false : room.web_echo === true);
 
 // ── Developer YAML: the config subset's writer and reader, exactly as settings.html had them (round-trip verified) ──
 export function toYaml(value, indent = 0) {

package/dist/ui/settings-mods.js

@@ -12,6 +12,7 @@ import { toast } from "/assets/ui-toast.js";
 import { confirmDialog } from "/assets/ui-confirm.js";
 import { startOwnerCssTrial } from "/assets/owner-css.js";
 import { AgentWidget, checkWidget, fleetBinds, instanceBinds } from "/assets/agent-widget.js";
+import { CardTitle } from "./settings-learn.js";
 import "./settings-strings.js";
 
 const tn = (k, ...v) => t(`settings.${k}`, ...v);
@@ -40,9 +41,9 @@ function why(body) {
 
 /** The parts a plan offers, each with its default: everything but custom CSS. */
 export function defaultChoice(plan) {
-  const c = { theme: false, identity: false, effects: false, ownerCss: false, widgets: {}, replace: false };
+  const c = { theme: false, identity: false, effects: false, ownerCss: false, ambient: false, widgets: {}, replace: false };
   for (const it of plan.items) {
-    if (it.part === "theme" || it.part === "identity") c[it.part] = true;
+    if (it.part === "theme" || it.part === "identity" || it.part === "ambient") c[it.part] = true;
     else if (it.part === "widget") c.widgets[it.slot] = true;
     else if (it.part === "effect") c.effects = true;
     // ownerCss stays false: "read it before turning it on" (r4 §4).
@@ -99,6 +100,19 @@ function PlanItem({ it, choice, setChoice, binds, fleet }) {
     return html`<li class="s-mod-item">${tick(tn(`modPartWidget_${it.slot}`), !!choice.widgets[it.slot], (v) => setChoice({ ...choice, widgets: { ...choice.widgets, [it.slot]: v } }))}
       <div class="s-mod-detail s-mod-widget">${w ? html`<${AgentWidget} slot=${it.slot} widget=${w} binds=${it.slot === "sidebar" ? fleet : binds} />` : null}</div></li>`;
   }
+  if (it.part === "ambient") {
+    // #2117: each ambient as it will be drawn: its preset, glyphs (pictures shown) and colours; every field below.
+    const glyph = (g, i) => typeof g === "string" ? html`<span key=${i} class="s-mod-text">${g}</span>`
+      : html`<img key=${i} class="s-mod-glyph" src=${`/ui/mods/staged/${g.asset}`} alt="" loading="lazy" />`;
+    const one = (kind) => {
+      const a = it[kind];
+      if (!a || !Array.isArray(a.glyphs)) return null;
+      return html`<div key=${kind} class="s-mod-kv"><span class="k">${a.preset}</span><span class="v s-mod-sws">${a.glyphs.map(glyph)}${(a.colors || []).map((c) => html`<${Swatch} key=${c} color=${c} />`)}</span></div>`;
+    };
+    return html`<li class="s-mod-item">${tick(tn("modPartAmbient"), !!choice.ambient, (v) => setChoice({ ...choice, ambient: v }))}
+      <div class="s-mod-detail">${one("loop")}${one("click")}
+        <details class="s-mod-raw"><summary>${tn("modAllFields")}</summary><pre class="s-mod-css-text">${JSON.stringify({ loop: it.loop, click: it.click }, null, 2)}</pre></details></div></li>`;
+  }
   if (it.part === "effect") {
     return html`<li class="s-mod-item">${tick(tn("modPartEffect", it.title), choice.effects, (v) => setChoice({ ...choice, effects: v }))}
       <div class="s-mod-detail"><span>${kib(it.bytes)} · ${tn("modRegions", it.regions.join(", "))}</span>${it.wants.length ? html`<span>${tn("modWants", it.wants.join(", "))}</span>` : null}</div></li>`;
@@ -119,7 +133,7 @@ function Plan({ staged, onDone }) {
   const [target, setTarget] = useState("");
   const [busy, setBusy] = useState(false);
   const [error, setError] = useState("");
-  const toInstance = choice.theme || choice.identity || !!choice.widgets.chat_header || !!choice.widgets.details;
+  const toInstance = choice.theme || choice.identity || choice.ambient || !!choice.widgets.chat_header || !!choice.widgets.details;
   const names = (app.instances || []).map((i) => i.name);
   const install = async () => {
     setBusy(true); setError("");
@@ -161,13 +175,13 @@ function Plan({ staged, onDone }) {
 
 function ExportForm() {
   const app = useStore(appStore);
-  const [f, setF] = useState({ instance: "", name: "", version: "1.0.0", title: "", theme: true, identity: true, header: true, details: true, sidebar: false, ownerCss: false });
+  const [f, setF] = useState({ instance: "", name: "", version: "1.0.0", title: "", theme: true, identity: true, header: true, details: true, ambient: true, sidebar: false, ownerCss: false });
   const [error, setError] = useState("");
   const set = (k) => (e) => setF({ ...f, [k]: e.target.type === "checkbox" ? e.target.checked : e.target.value });
   const go = async () => {
     setError("");
     const body = { instance: f.instance || undefined, name: f.name, version: f.version, title: f.title,
-      include: { theme: f.theme, identity: f.identity, ownerCss: f.ownerCss, widgets: { chat_header: f.header, details: f.details, sidebar: f.sidebar } } };
+      include: { theme: f.theme, identity: f.identity, ambient: f.ambient, ownerCss: f.ownerCss, widgets: { chat_header: f.header, details: f.details, sidebar: f.sidebar } } };
     let res;
     try { res = await fetch("/ui/mods/export", { method: "POST", credentials: "same-origin", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body) }); }
     catch { setError(tn("modFailed", "network")); return; }
@@ -181,7 +195,7 @@ function ExportForm() {
   return html`<details class="s-mod-export"><summary>${tn("modExport")}</summary>
     <p class="sub">${tn("modExportLead")}</p>
     <label class="field"><span>${tn("modExportInstance")}</span><select value=${f.instance} onChange=${set("instance")}><option value="">—</option>${(app.instances || []).map((i) => html`<option key=${i.name} value=${i.name}>${i.name}</option>`)}</select></label>
-    <div class="s-mod-boxes">${box("theme", tn("modPartTheme"))}${box("identity", tn("modPartIdentity"))}${box("header", tn("modPartWidget_chat_header"))}${box("details", tn("modPartWidget_details"))}${box("sidebar", tn("modPartWidget_sidebar"))}${box("ownerCss", tn("modPartCss"))}</div>
+    <div class="s-mod-boxes">${box("theme", tn("modPartTheme"))}${box("identity", tn("modPartIdentity"))}${box("header", tn("modPartWidget_chat_header"))}${box("details", tn("modPartWidget_details"))}${box("ambient", tn("modPartAmbient"))}${box("sidebar", tn("modPartWidget_sidebar"))}${box("ownerCss", tn("modPartCss"))}</div>
     <label class="field"><span>${tn("modExportName")}</span><input value=${f.name} placeholder="my-look" onInput=${set("name")} /></label>
     <label class="field"><span>${tn("modExportVersion")}</span><input value=${f.version} onInput=${set("version")} /></label>
     <label class="field"><span>${tn("modExportTitle")}</span><input value=${f.title} onInput=${set("title")} /></label>
@@ -204,8 +218,8 @@ export function ModsCard() {
     setState(b && Array.isArray(b.mods) ? { mods: b.mods.filter((m) => m && typeof m.id === "string"), staged, proposals } : { failed: true });
   };
   useEffect(() => { load(); }, []);
-  if (!state) return html`<section class="card s-appearance s-mods"><h3>${tn("modsTitle")}</h3><p class="sub">…</p></section>`;
-  if (state.failed) return html`<section class="card s-appearance s-mods"><h3>${tn("modsTitle")}</h3><p class="err">${tn("modsLoadFailed")}</p></section>`;
+  if (!state) return html`<section class="card s-appearance s-mods"><${CardTitle} title=${tn("modsTitle")} topic="mods" /><p class="sub">…</p></section>`;
+  if (state.failed) return html`<section class="card s-appearance s-mods"><${CardTitle} title=${tn("modsTitle")} topic="mods" /><p class="err">${tn("modsLoadFailed")}</p></section>`;
   const stage = async () => {
     const f = file.current && file.current.files && file.current.files[0];
     if (!f) return;
@@ -238,7 +252,7 @@ export function ModsCard() {
     if (!r || !r.ok) { toast(tn("modFailed", r ? r.status : "network"), false); return; }
     download(await r.text(), `${m.name}-${m.version}.agendmod.json`);
   };
-  return html`<section class="card s-appearance s-mods"><h3>${tn("modsTitle")}</h3>
+  return html`<section class="card s-appearance s-mods"><${CardTitle} title=${tn("modsTitle")} topic="mods" />
     <p class="sub">${tn("modsLead")}</p>
     ${state.staged ? html`<${Plan} key=${state.staged.stage} staged=${state.staged} onDone=${load} />` : html`<div class="s-mod-import">
       <label class="btn"><${Icon} name="attach" size=${16} /><span>${tn("modChoose")}</span>