@songsid/agend 2.2.0-beta.9 → 2.3.0-beta.1

package/dist/ui/shared/agent-widget.js

@@ -0,0 +1,248 @@
+// #1629 r4-4 (option A): widgets — an agent's in its own chat header and Details page, a person's in their sidebar —
+// drawn by the page's own components from a closed declarative spec and its values (src/web-widget.ts). Nothing from a
+// mod becomes markup, script, a handler, a URL or a style: text is text nodes, a number fills a <progress> or an SVG
+// polyline's points, and tones are fixed class tokens. Colours are the theme's tokens (and a person's own CSS). The box
+// always carries the page's own ✦ chip, so a widget never reads as AgEnD's chrome, and nothing in it can be clicked.
+//
+// What the host sends is checked again here with the same rules; a widget that fails is not drawn, and a value that
+// fails shows "—". A `bind` is a value the page already has (the instance's own state, context and cost; the fleet's
+// counts in the person's sidebar only) — nothing new is fetched for it.
+import { html } from "./app-html.js";
+import { register, t } from "./app-i18n.js";
+import { statusFacet } from "./instance-nav.js";
+import { themesShown, themesStore } from "./app-themes.js";
+import { onPrefsChanged, prefInForce, savePref } from "./app-prefs.js";
+import { createStore } from "./app-store.js";
+import { safeMode } from "./owner-css.js";
+
+register("widget", {
+  en: {
+    label: "Widget: {0}",
+    chip: "A widget — drawn by AgEnD from its owner's data",
+    byHuman: "placed by a person",
+    none: "—",
+  },
+  "zh-TW": {
+    label: "小工具：{0}",
+    chip: "小工具——由 AgEnD 依擁有者的資料繪製",
+    byHuman: "由人放置",
+    none: "—",
+  },
+});
+
+export const WIDGET_ITEM_TYPES = ["stat", "progress", "text", "list", "badge", "spark"];
+export const WIDGET_TONES = ["ok", "warn", "bad", "info", "muted"];
+const INSTANCE_BINDS = ["state", "context_pct", "cost_usd"];
+const FLEET_BINDS = ["fleet.idle", "fleet.working", "fleet.needs_you", "fleet.stopped"];
+export const SLOT_RULES = {
+  chat_header: { maxItems: 4, types: ["stat", "progress", "text", "badge"], binds: INSTANCE_BINDS },
+  details: { maxItems: 8, types: WIDGET_ITEM_TYPES, binds: INSTANCE_BINDS },
+  sidebar: { maxItems: 8, types: WIDGET_ITEM_TYPES, binds: FLEET_BINDS },
+};
+const BINDS_FOR = {
+  stat: ["context_pct", "cost_usd", ...FLEET_BINDS], progress: ["context_pct"], text: ["state"], badge: ["state"], list: [], spark: [],
+};
+const ITEM_KEYS = {
+  stat: ["type", "label", "key", "bind", "unit"], progress: ["type", "label", "key", "bind", "max"], text: ["type", "label", "key", "bind"],
+  list: ["type", "label", "key"], badge: ["type", "label", "key", "bind", "tone", "tones"], spark: ["type", "label", "key"],
+};
+const LABEL_REQUIRED = ["stat", "progress", "spark"];
+const KEY = /^[a-z][a-z0-9_]{0,31}$/;
+const NUMBER_MAX = 1e15;
+const own = (o, k) => !!o && Object.prototype.hasOwnProperty.call(o, k);
+const isObj = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+
+// One line of text, as the host's canonicalText: NFC, no control, format or separator character but the zero-width
+// joiner, at least one character that draws something, 1..max graphemes.
+const FORBIDDEN = /(?!‍)[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/u;
+const VISIBLE = /[^\p{M}\p{C}\p{Z}ᅟᅠㅤﾠ⠀]/u;
+let graphemes = null;
+export function lineOk(s, max) {
+  if (typeof s !== "string" || s.normalize("NFC") !== s || FORBIDDEN.test(s) || s.trim() !== s || !VISIBLE.test(s)) return false;
+  try { graphemes ??= new Intl.Segmenter(undefined, { granularity: "grapheme" }); } catch { return false; }
+  const n = [...graphemes.segment(s)].length;
+  return n >= 1 && n <= max;
+}
+const isNumber = (v) => typeof v === "number" && Number.isFinite(v) && Math.abs(v) <= NUMBER_MAX;
+
+/** Whether `v` is a value an item of `type` can show (web-widget.ts valueFits). */
+export function valueFits(type, v) {
+  switch (type) {
+    case "stat": return isNumber(v) || lineOk(v, 24);
+    case "progress": return isNumber(v);
+    case "text": return lineOk(v, 120);
+    case "badge": return lineOk(v, 24);
+    case "list": return Array.isArray(v) && v.length >= 1 && v.length <= 6 && v.every((s) => lineOk(s, 60));
+    case "spark": return Array.isArray(v) && v.length >= 2 && v.length <= 48 && v.every(isNumber);
+    default: return false;
+  }
+}
+
+/**
+ * A widget `{ spec, data, by? }` for `slot`, checked again: `{ widget }`, or `{ problem }` (where, and what) when its
+ * spec fails — then the whole widget is not drawn. A data value that fails is left out (shown as "—").
+ */
+export function explainWidget(slot, w) {
+  const no = (problem) => ({ problem });
+  const rules = own(SLOT_RULES, slot) ? SLOT_RULES[slot] : null;
+  if (!rules) return no("slot");
+  if (!isObj(w) || !isObj(w.spec)) return no("spec: an object { v: 1, title, items }");
+  const s = w.spec;
+  const extra = Object.keys(s).find((k) => !["v", "title", "items"].includes(k));
+  if (extra) return no(`spec.${extra}: unknown key`);
+  if (s.v !== 1) return no("spec.v: must be 1");
+  if (!lineOk(s.title, 24)) return no("spec.title: 1..24 characters on one line");
+  if (!Array.isArray(s.items) || s.items.length < 1 || s.items.length > rules.maxItems) return no(`spec.items: 1..${rules.maxItems} items`);
+  const items = [];
+  for (const [i, it] of s.items.entries()) {
+    const at = `spec.items.${i}`;
+    if (!isObj(it) || !rules.types.includes(it.type)) return no(`${at}.type: ${rules.types.join(", ")}`);
+    const unknown = Object.keys(it).find((k) => !ITEM_KEYS[it.type].includes(k));
+    if (unknown) return no(`${at}.${unknown}: unknown key`);
+    if ((it.label !== undefined || LABEL_REQUIRED.includes(it.type)) && !lineOk(it.label, 24)) return no(`${at}.label: 1..24 characters`);
+    if ((it.key === undefined) === (it.bind === undefined)) return no(`${at}: exactly one of key or bind`);
+    if (it.key !== undefined && !(typeof it.key === "string" && KEY.test(it.key))) return no(`${at}.key: a-z, 0-9 and _`);
+    if (it.bind !== undefined && !(BINDS_FOR[it.type].includes(it.bind) && rules.binds.includes(it.bind))) return no(`${at}.bind: ${BINDS_FOR[it.type].filter((b) => rules.binds.includes(b)).join(", ") || "none here"}`);
+    if (it.unit !== undefined && !lineOk(it.unit, 8)) return no(`${at}.unit: 1..8 characters`);
+    if (it.max !== undefined && !(isNumber(it.max) && it.max > 0)) return no(`${at}.max: a number > 0`);
+    if (it.tone !== undefined && !WIDGET_TONES.includes(it.tone)) return no(`${at}.tone: ${WIDGET_TONES.join(", ")}`);
+    let tones;
+    if (it.tones !== undefined) {
+      if (!isObj(it.tones)) return no(`${at}.tones: { value: tone }`);
+      tones = new Map();
+      for (const [k, v] of Object.entries(it.tones)) { if (!lineOk(k, 24) || !WIDGET_TONES.includes(v)) return no(`${at}.tones: { value: ${WIDGET_TONES.join(" | ")} }`); tones.set(k, v); }
+      if (tones.size < 1 || tones.size > 8) return no(`${at}.tones: 1..8 entries`);
+    }
+    items.push({ type: it.type, label: it.label, key: it.key, bind: it.bind, unit: it.unit, max: it.max, tone: it.tone, tones });
+  }
+  const data = new Map();
+  if (isObj(w.data)) items.forEach((it, i) => { if (it.key && own(w.data, it.key) && valueFits(it.type, w.data[it.key])) data.set(`${i}`, w.data[it.key]); });
+  return { widget: { title: s.title, items, data, by: w.by === "human" ? "human" : "agent" } };
+}
+/** explainWidget's widget, or null. */
+export function checkWidget(slot, w) { return explainWidget(slot, w).widget || null; }
+
+/**
+ * What the host would refuse in a person's `{ spec, data }` for `slot` (its whole check, web-widget.ts and web-prefs.ts),
+ * or null — so the editor can say why before anything is saved.
+ */
+export function widgetProblem(slot, v) {
+  if (!isObj(v) || Object.keys(v).length !== 2 || !own(v, "spec") || !own(v, "data")) return "{ \"spec\": …, \"data\": … }";
+  const r = explainWidget(slot, v);
+  if (r.problem) return r.problem;
+  if (!isObj(v.data)) return "data: an object { key: value }";
+  for (const [k, val] of Object.entries(v.data)) {
+    const users = r.widget.items.filter((it) => it.key === k);
+    if (!users.length) return `data.${k}: no item shows this key`;
+    const bad = users.find((it) => !valueFits(it.type, val));
+    if (bad) return `data.${k}: not a value a ${bad.type} shows`;
+  }
+  const bytes = (x) => new TextEncoder().encode(JSON.stringify(x)).length;
+  if (bytes(v.spec) > 2048) return "spec: at most 2048 bytes";
+  if (bytes(v.data) > 4096) return "data: at most 4096 bytes";
+  return null;
+}
+
+/** The values the page has for one instance: its state word (a sidebar facet), context % and cost. */
+export function instanceBinds(inst, exec, awaiting) {
+  if (!inst) return {};
+  return {
+    state: statusFacet(inst, exec, awaiting),
+    context_pct: isNumber(inst.context_pct) ? Math.round(Math.max(0, Math.min(100, inst.context_pct))) : undefined,
+    cost_usd: isNumber(inst.cost) ? inst.cost : undefined,
+  };
+}
+/** The fleet's counts, for the person's sidebar widget only: how many instances are idle, working, need you, stopped. */
+export function fleetBinds(instances, exec, awaiting) {
+  const n = { "fleet.idle": 0, "fleet.working": 0, "fleet.needs_you": 0, "fleet.stopped": 0 };
+  for (const it of Array.isArray(instances) ? instances : []) {
+    const f = statusFacet(it, exec && exec[it.name], awaiting && own(awaiting, it.name) ? awaiting[it.name] : null);
+    n[f === "needs" ? "fleet.needs_you" : f === "working" ? "fleet.working" : f === "idle" ? "fleet.idle" : "fleet.stopped"] += 1;
+  }
+  return n;
+}
+
+let numbers = null;
+function fmt(v) {
+  try { numbers ??= new Intl.NumberFormat(undefined, { maximumFractionDigits: 2 }); return numbers.format(v); } catch { return String(v); }
+}
+/** An item's value: its data, or its bind; undefined when there is none (shown as "—"). */
+function valueOf(item, i, w, binds) {
+  if (item.key) return w.data.get(`${i}`);
+  const v = binds && own(binds, item.bind) ? binds[item.bind] : undefined;
+  return item.bind === "state" ? (lineOk(v, 24) ? v : undefined) : isNumber(v) ? v : undefined;
+}
+function shown(item, v) {
+  if (v === undefined) return t("widget.none");
+  if (item.bind === "cost_usd") return `$${v.toFixed(2)}`;
+  if (item.bind === "context_pct") return `${v}%`;
+  return typeof v === "number" ? fmt(v) : v;
+}
+/** The sparkline's points in a 100×24 box (numbers only; nothing else reaches the SVG). */
+export function sparkPoints(values) {
+  const lo = Math.min(...values), hi = Math.max(...values), span = hi - lo || 1;
+  return values.map((v, i) => `${((i / (values.length - 1)) * 100).toFixed(2)},${(22 - ((v - lo) / span) * 20).toFixed(2)}`).join(" ");
+}
+
+function Item({ item, v }) {
+  const label = item.label ? html`<span class="aw-label">${item.label}</span>` : null;
+  switch (item.type) {
+    case "stat":
+      return html`<div class="aw-item aw-stat">${label}<span class="aw-value">${shown(item, v)}${v !== undefined && item.unit ? html`<span class="aw-unit">${item.unit}</span>` : null}</span></div>`;
+    case "progress": {
+      const max = item.max ?? 100;
+      const pct = v === undefined ? null : Math.round((Math.max(0, Math.min(max, v)) / max) * 100);
+      // No value: no bar at all (a <progress> without one is the browser's animated "busy" bar), only "—".
+      return html`<div class="aw-item aw-progress">${label}${pct === null ? null : html`<progress class="aw-bar" max=${max} value=${Math.max(0, Math.min(max, v))} aria-label=${item.label}></progress>`}<span class="aw-value">${pct === null ? t("widget.none") : `${pct}%`}</span></div>`;
+    }
+    case "text":
+      return html`<div class="aw-item aw-text">${label}<span class="aw-value">${shown(item, v)}</span></div>`;
+    case "badge": {
+      const tone = v !== undefined && item.tones && item.tones.has(v) ? item.tones.get(v) : item.tone || "muted";
+      return html`<div class="aw-item aw-badge-item">${label}<span class=${`aw-badge aw-tone-${WIDGET_TONES.includes(tone) ? tone : "muted"}`}>${shown(item, v)}</span></div>`;
+    }
+    case "list":
+      return html`<div class="aw-item aw-list">${label}${v === undefined ? html`<span class="aw-value">${t("widget.none")}</span>` : html`<ul>${v.map((line, i) => html`<li key=${i}>${line}</li>`)}</ul>`}</div>`;
+    case "spark":
+      return html`<div class="aw-item aw-spark-item">${label}${v === undefined ? html`<span class="aw-value">${t("widget.none")}</span>`
+        : html`<svg class="aw-spark" viewBox="0 0 100 24" preserveAspectRatio="none" aria-hidden="true"><polyline points=${sparkPoints(v)} /></svg><span class="aw-value">${fmt(v[v.length - 1])}</span>`}</div>`;
+    default: return null;
+  }
+}
+
+/** One widget, checked (checkWidget's result), in `slot`. `binds`: instanceBinds or fleetBinds. */
+export function AgentWidget({ slot, widget, binds, tools = null }) {
+  if (!widget) return null;
+  return html`<section data-trust="widget" class=${`aw aw-${slot}`} aria-label=${t("widget.label", widget.title)} data-widget-slot=${slot}>
+    <div class="aw-head"><span class="aw-chip" title=${t("widget.chip")}>✦ ${widget.title}</span>
+      ${widget.by === "human" ? html`<span class="aw-by">${t("widget.byHuman")}</span>` : null}${tools}</div>
+    <div class="aw-items">${widget.items.map((item, i) => html`<${Item} key=${i} item=${item} v=${valueOf(item, i, widget, binds)} />`)}</div>
+  </section>`;
+}
+
+/** An agent's widget in `slot` ("chat_header" | "details"), checked; null when none, or agents' looks are not shown here. */
+export function widgetFor(name, slot) {
+  const s = themesStore.get();
+  if (!s.shown || !themesShown() || !own(s.widgets, name)) return null;
+  const slots = s.widgets[name];
+  return isObj(slots) && own(slots, slot) ? checkWidget(slot, slots[slot]) : null;
+}
+
+const SIDEBAR_KEY = "widget.sidebar";
+const publicLink = () => typeof document !== "undefined" && !!document.body && document.body.dataset.publicLink === "1";
+/** The person's own sidebar widget (a synced preference), raw; null when none. Never on the public link or in safe mode. */
+export function sidebarWidgetRaw() {
+  if (publicLink() || safeMode()) return null;
+  const f = prefInForce(SIDEBAR_KEY);
+  let v = f ? f.value : undefined;
+  if (!f) { try { v = JSON.parse(localStorage.getItem("agend_widget_sidebar") || "null"); } catch { v = null; } }
+  return isObj(v) ? v : null;
+}
+/** The person's sidebar widget, checked; null when none. */
+export function sidebarWidget() { const v = sidebarWidgetRaw(); return v ? checkWidget("sidebar", v) : null; }
+/** Bumped when the person's sidebar widget changes (here, or on another device), so the sidebar redraws. */
+export const sidebarWidgetStore = createStore({ n: 0 });
+const bump = () => sidebarWidgetStore.set((s) => ({ n: s.n + 1 }));
+onPrefsChanged((changed) => { if (changed.has(SIDEBAR_KEY)) bump(); });
+/** Set (or with null, remove) the person's sidebar widget on all their devices. */
+export function setSidebarWidget(value) { savePref(SIDEBAR_KEY, value); bump(); }

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

@@ -68,6 +68,7 @@ register("app", {
     previews: "Allow HTML previews", tour: "Tour", tourTitle: "Show the web chat tour again",
     needsYou: "needs you", approxNote: "Read from the terminal, so approximate", chat: "Chat", details: "Details", log: "Log", instanceViews: "Views of {0}",
     textSize: "Text size: {0}", textSize_s: "S", textSize_m: "M", textSize_l: "L", textSize_fit: "Fit", usage: "Usage", usageHide: "Hide usage",
+    ownerCssKeep: "Keep this custom CSS?", ownerCssKeepLeft: "Reverts in {0} s", ownerCssKeepYes: "Keep", ownerCssKeepNo: "Revert",
     statusRunning: "running", statusStopped: "stopped", statusPaused: "paused", statusCrashed: "crashed", statusWorking: "working", statusStuck: "looks stuck", statusIdle: "idle",
     connReconnecting: "Can't reach AgEnD — it may be restarting. Reconnecting…", connReconnectingIn: "Can't reach AgEnD — it may be restarting. Trying again in {0} s.",
     hydrating: "Loading what is open now…", hydrateFailed: "Could not load what is open now (prompts, ticks).",
@@ -98,7 +99,8 @@ register("app", {
     theme: "主題", themeSystem: "跟隨系統", themeLight: "淺色", themeDark: "深色", language: "語言",
     previews: "允許預覽 HTML", tour: "導覽", tourTitle: "再看一次網頁聊天導覽",
     needsYou: "等你回應", approxNote: "從終端畫面判讀，僅供參考", chat: "聊天", details: "詳細資訊", log: "紀錄", instanceViews: "{0} 的檢視",
-    textSize: "字級：{0}", textSize_s: "小", textSize_m: "中", textSize_l: "大", textSize_fit: "剛好填滿", usage: "用量", usageHide: "隱藏用量",
+    textSize: "字級：{0}", textSize_s: "小", textSize_m: "中", textSize_l: "大", textSize_fit: "填滿", usage: "用量", usageHide: "隱藏用量",
+    ownerCssKeep: "保留這份自訂 CSS？", ownerCssKeepLeft: "{0} 秒後還原", ownerCssKeepYes: "保留", ownerCssKeepNo: "還原",
     statusRunning: "執行中", statusStopped: "已停止", statusPaused: "已暫停", statusCrashed: "已當掉", statusWorking: "工作中", statusStuck: "似乎卡住", statusIdle: "閒置",
     connReconnecting: "連不上 AgEnD——可能正在重新啟動。正在重新連線…", connReconnectingIn: "連不上 AgEnD——可能正在重新啟動。{0} 秒後再試。",
     hydrating: "正在載入目前的狀態…", hydrateFailed: "無法載入目前的狀態（提示、送達標記）。",

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

@@ -33,13 +33,32 @@ export const SYNCED = {
   "nav.favorites": { ls: "agend_favorites", ...json },   // #1664
   "preview.optIn": { ls: "agend_html_preview", toLocal: (v) => (v ? "on" : null), fromLocal: (s) => (s === "on" ? true : undefined) },
   "names.primary": { ls: "agend_names_primary", toLocal: (v) => (v === "instance" ? v : null), fromLocal: (s) => (s === "instance" ? s : undefined) },   // #1722
+  // #1629 r2 (d): "Show agents' themes and effects" — on unless turned off (only "off" is cached).
+  "fx.show": { ls: "agend_fx_show", toLocal: (v) => (v === false ? "off" : null), fromLocal: (s) => (s === "off" ? false : undefined) },
+  // #1629 r4.1 Q3 (a): the identity card's size — every card's default (M unless chosen), and the cards set apart.
+  "card.size": { ls: "agend_card_size", toLocal: (v) => (v === "s" || v === "l" ? v : null), fromLocal: (s) => (s === "s" || s === "l" ? s : undefined) },
+  "card.sizeByInstance": { ls: "agend_card_sizes", ...json },
+  // #1629 r4-4: the person's own sidebar widget ({ spec, data }), drawn by the page's own components.
+  "widget.sidebar": { ls: "agend_widget_sidebar", ...json },
+  // #1958: where identity colours show by default (ring + bar unless chosen), and the host's switch to turn them off.
+  "color.show": { ls: "agend_color_show", ...json },
+  "color.off": { ls: "agend_color_off", toLocal: (v) => (v === true ? "on" : null), fromLocal: (s) => (s === "on" ? true : undefined) },
 };
+// #1629: fixed personal scope. A separate session-bound owner-effect store synchronizes these, never this host cache.
+export const OWNER_EFFECT_PREF_KEYS = Object.freeze(["fx.sidebar", "fx.header", "fx.page", "fx.box", "fx.cursor"]);
+for (const spec of Object.values(SYNCED)) spec.scope = "host";
+for (const key of OWNER_EFFECT_PREF_KEYS) SYNCED[key] = Object.freeze({ scope: "person", ls: null });
+for (const spec of Object.values(SYNCED)) Object.freeze(spec);
+Object.freeze(SYNCED);
+const HOST_KEYS = Object.keys(SYNCED).filter(key => SYNCED[key].scope === "host");
+const hostKey = key => own(SYNCED, key) && SYNCED[key].scope === "host";
+const hostValues = values => Object.fromEntries(HOST_KEYS.filter(key => own(values, key)).map(key => [key, values[key]]));
 const own = (o, k) => !!o && Object.prototype.hasOwnProperty.call(o, k);
 const now = () => (typeof performance !== "undefined" ? performance.now() : Date.now());
 
 function readLocal(key) { try { return localStorage.getItem(key); } catch { return null; } }
 function writeLocal(key, s) { try { if (s == null) localStorage.removeItem(key); else localStorage.setItem(key, s); } catch { /* this page only */ } }
-function cache(key, value) { const k = SYNCED[key]; writeLocal(k.ls, value == null ? null : k.toLocal(value)); }
+function cache(key, value) { if (!hostKey(key)) return; const k = SYNCED[key]; writeLocal(k.ls, value == null ? null : k.toLocal(value)); }
 const inStep = () => readLocal(SYNCED_FLAG) === "1";
 
 function pageHost() {
@@ -51,7 +70,7 @@ function pageHost() {
 
 const initial = typeof document !== "undefined" ? pageHost() : null;
 let rev = initial ? initial.rev : null;
-let host = initial ? initial.values : null;
+let host = initial ? hostValues(initial.values) : null;
 const pending = new Map();     // key → value chosen here, not sent yet
 const mine = new Map();        // key → value chosen here whose write is not over (pending or out)
 const inflight = new Map();    // key → writes sent and not answered yet
@@ -63,7 +82,7 @@ const listeners = new Set();
 // the host does not have: the default, on a device in step with the host; this device's own (to upload) otherwise.
 if (host) {
   const step = inStep();
-  for (const key of Object.keys(SYNCED)) {
+  for (const key of HOST_KEYS) {
     if (own(host, key)) cache(key, host[key]);
     else if (step) cache(key, null);
   }
@@ -80,14 +99,14 @@ export function prefsWritable() {
  * in step) — the caller reads this browser's copy.
  */
 export function prefInForce(key) {
-  if (!own(SYNCED, key)) return null;
+  if (!hostKey(key)) return null;
   if (mine.has(key)) return { value: mine.get(key) };
   if (host && own(host, key)) return { value: host[key] };
   if (initial && inStep()) return { value: undefined };
   return null;
 }
 /** The host's value for a key as this page last saw it (undefined: not set there, or not known). */
-export function hostPref(key) { return host && own(host, key) ? host[key] : undefined; }
+export function hostPref(key) { return hostKey(key) && host && own(host, key) ? host[key] : undefined; }
 /** Called with the keys another device changed, after they are cached and applied here. Returns the unsubscribe. */
 export function onPrefsChanged(fn) { listeners.add(fn); return () => listeners.delete(fn); }
 
@@ -97,7 +116,7 @@ const isView = (body) => !!body && typeof body.rev === "number" && !!body.values
 function take(body) {
   if (!isView(body) || (rev !== null && body.rev < rev)) return false;
   rev = body.rev;
-  host = body.values;
+  host = hostValues(body.values);
   return true;
 }
 
@@ -106,7 +125,7 @@ function take(body) {
  * (the public link, the anonymous reader): this browser only, as before.
  */
 export function savePref(key, value) {
-  if (!own(SYNCED, key)) return;
+  if (!hostKey(key)) return;
   cache(key, value);
   if (!prefsWritable()) return;
   pending.set(key, value);
@@ -165,8 +184,8 @@ export async function refresh() {
     body = res.ok ? await res.json() : null;
   } catch { body = null; }
   if (!isView(body)) return false;
-  const before = new Map(Object.keys(SYNCED).map((key) => [key, own(host, key) ? SYNCED[key].toLocal(host[key]) : null]));
-  if (take(body)) align(Object.keys(SYNCED), { before });
+  const before = new Map(HOST_KEYS.map((key) => [key, own(host, key) ? SYNCED[key].toLocal(host[key]) : null]));
+  if (take(body)) align(HOST_KEYS, { before });
   return true;
 }
 
@@ -179,6 +198,7 @@ export async function refresh() {
 function align(keys, opts = {}) {
   const changed = new Set();
   for (const key of keys) {
+    if (!hostKey(key)) continue;
     if (pending.has(key) || inflight.has(key)) continue;
     const k = SYNCED[key];
     const want = own(host, key) ? k.toLocal(host[key]) : null;
@@ -216,7 +236,7 @@ function apply(changed) {
  */
 export async function migratePrefs() {
   if (!prefsWritable() || inStep()) return false;
-  for (const key of Object.keys(SYNCED)) {
+  for (const key of HOST_KEYS) {
     if (own(host, key)) continue;
     const local = SYNCED[key].fromLocal(readLocal(SYNCED[key].ls));
     if (local === undefined) continue;

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

@@ -2,7 +2,7 @@
 // a test runs both over one list of cases). Pure: no DOM, no history.
 
 export const FLEET_TABS = ["tasks", "schedules", "teams", "org", "cache", "config"];
-export const SETTINGS_SECTIONS = ["device", "agents", "bots", "classic", "general", "web", "advanced"];   // #1604: device first
+export const SETTINGS_SECTIONS = ["device", "appearance", "agents", "bots", "classic", "general", "web", "advanced"];   // #1604: device first
 const MAX_INSTANCE_NAME = 128;
 const PATH_SEPARATOR_OR_CONTROL = /[/\\\u0000-\u001f\u007f]/;
 
@@ -62,6 +62,28 @@ export function routePath(route) {
   if (route.panel === "log") return logPath(route.instance);
   return route.instance ? chatPath(route.instance) : "/ui";
 }
+/**
+ * #1990: a text with the in-app links the server put on it (ranges of the text: { offset, length, url }) as segments —
+ * { text } or { text, href }. Only a route this table parses as an instance's chat or View becomes a link (its href
+ * rebuilt here); a range out of order, out of the text, or anything else stays text. No target: the router opens it.
+ */
+export function textLinkSegments(text, links) {
+  const s = String(text == null ? "" : text);
+  const out = [];
+  let at = 0;
+  for (const l of Array.isArray(links) ? links.slice(0, 16) : []) {
+    if (!l || !Number.isInteger(l.offset) || !Number.isInteger(l.length) || typeof l.url !== "string") continue;
+    if (l.offset < at || l.length < 1 || l.offset + l.length > s.length || !/^\/[^?#\s]*$/.test(l.url)) continue;
+    const route = parseRoute(l.url);
+    if (!route || !route.instance || (route.panel !== "chat" && route.panel !== "view")) continue;
+    if (l.offset > at) out.push({ text: s.slice(at, l.offset) });
+    out.push({ text: s.slice(l.offset, l.offset + l.length), href: routePath(route) });
+    at = l.offset + l.length;
+  }
+  if (at < s.length || !out.length) out.push({ text: s.slice(at) });
+  return out;
+}
+
 /** One string per route: a change of it is a new navigation (a new lease for the panel, §4). */
 export function routeKey(route) {
   if (!route) return "none";

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

@@ -49,7 +49,7 @@ export function SessionMenu() {
     <button ref=${btn} type="button" class="side-row" aria-haspopup="dialog" aria-expanded=${open ? "true" : "false"}
       onClick=${() => { const next = !open; setOpen(next); if (next) refresh(); }}>
       <span class=${`dot${me ? " ok" : ""}`} aria-hidden="true"></span><span class="grow">${label}</span>${me ? html`<span class="meta">${me.label}</span>` : null}</button>
-    ${open ? html`<div ref=${pop} class="pop" role="dialog" aria-label=${t("app.session")} onKeyDown=${onKey}>
+    ${open ? html`<div data-trust="session" ref=${pop} class="pop" role="dialog" aria-label=${t("app.session")} onKeyDown=${onKey}>
       ${!me ? html`<h3>${t("app.signedOut")}</h3><a class="btn" href=${`/signin?next=${encodeURIComponent(location.pathname)}`}>${t("app.signIn")}</a>` : html`
         <h3>${t("app.signedIn")} · ${me.label}</h3>
         <p class="sub">${t("app.expires", clock(me.expiresAt), span(me.idleMs))}</p>

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

@@ -5,6 +5,7 @@ import { html, useEffect, useLayoutEffect, useRef, useState } from "./app-html.j
 import { Icon } from "./ui-icons.js";
 import { Toasts } from "./ui-toast.js";
 import { ConfirmHost } from "./ui-confirm.js";
+import { ColorDialogHost } from "./identity-color.js";
 import { t, lang, setLang, onLang } from "./app-i18n.js";
 import { appStore, createStore, useStore } from "./app-store.js";
 import { navStore } from "./app-nav.js";
@@ -14,6 +15,8 @@ import { savePref } from "./app-prefs.js";
 import { ErrorState, Skeleton } from "./ui-states.js";
 import { InstanceNav, RosterNav, namesStore, setNamesPrimary } from "./instance-nav.js";
 import { UsageRail, usageRailStore } from "./header-tools.js";
+import { OwnerCssKeepBar } from "./owner-css.js";
+import { AgentWidget, fleetBinds, sidebarWidget, sidebarWidgetStore } from "./agent-widget.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(), keyboard: false, dialog: null, side: null });
@@ -175,7 +178,7 @@ function SidebarResize() {
     handle.addEventListener("pointercancel", cancel);
     handle.addEventListener("lostpointercapture", cancel);
   };
-  return html`<div class="side-resize" role="separator" aria-orientation="vertical" tabindex="0" aria-controls="sidebar"
+  return html`<div data-trust="navigation" class="side-resize" role="separator" aria-orientation="vertical" tabindex="0" aria-controls="sidebar"
     aria-label=${t("app.resizeSidebar")} title=${t("app.resizeSidebarHint")} aria-valuemin=${String(SIDEBAR_W.min)}
     aria-valuemax=${String(clampSidebarWidth(Infinity, mainBudget()))} aria-valuenow=${String(now)}
     onKeyDown=${onKey} onPointerDown=${onDown} ondblclick=${() => setSidebarWidth(null)}></div>`;
@@ -255,13 +258,13 @@ function Sidebar({ route, onNewInstance, viewOnly }) {
   // View-only (an anonymous reader, #1408 §3): View and a way to sign in — nothing that needs a session is rendered.
   if (viewOnly) {
     return html`<aside id="sidebar" class="sidebar" aria-label=${t("app.menu")}>
-      <div class="side-head">
+      <div class="side-head" data-trust="navigation">
         <a class="brand" href="/view" 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>
       </div>
-      <nav class="side-nav" aria-label=${t("app.menu")}>${navLink("view", "/view", "view", t("app.view"))}</nav>
+      <nav data-trust="navigation" class="side-nav" aria-label=${t("app.menu")}>${navLink("view", "/view", "view", t("app.view"))}</nav>
       ${shell.side ? html`<${shell.side.Component} />` : html`<${ViewOnlyNav} route=${route} />`}
-      <div class="side-foot">
+      <div class="side-foot" data-trust="navigation">
         <a class="side-row" href=${signInHref()}><${Icon} name="user" /><span>${t("app.signIn")}</span></a>
         <${PrefsPopover} />
       </div>
@@ -274,12 +277,12 @@ function Sidebar({ route, onNewInstance, viewOnly }) {
   const overview = html`<a class=${`side-row side-overview${onFleet ? " active" : ""}`} href=${fleetPath("org")}
     aria-current=${onFleet ? "page" : undefined} onClick=${closeDrawer}><${Icon} name="org" /><span class="grow">${t("app.fleetOverview")}</span></a>`;
   return html`<aside id="sidebar" class="sidebar" aria-label=${t("app.menu")}>
-    <div class="side-head">
+    <div class="side-head" data-trust="navigation">
       <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="plus" /></button>
     </div>
-    <nav class="side-nav" aria-label=${t("app.menu")}>
+    <nav data-trust="navigation" class="side-nav" aria-label=${t("app.menu")}>
       ${overview}
       ${navLink("needs", NEEDS_PATH, "inbox", t("app.needsNav"), needsCount)}
       ${navLink("fleet", openInstance ? detailsPath(openInstance) : "/ui/fleet", "fleet", t("app.fleet"))}
@@ -287,7 +290,8 @@ function Sidebar({ route, onNewInstance, viewOnly }) {
     </nav>
     ${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">
+    <${SidebarWidget} app=${app} />
+    <div class="side-foot" data-trust="navigation">
       ${navLink("settings", settingsPath(), "settings", t("app.settings"))}
       <${SessionMenu} />
     </div>
@@ -295,6 +299,13 @@ function Sidebar({ route, onNewInstance, viewOnly }) {
   </aside>`;
 }
 
+/** #1629 r4-4: the person's own sidebar widget (their synced preference), with the fleet's counts. */
+function SidebarWidget({ app }) {
+  useStore(sidebarWidgetStore);
+  const widget = sidebarWidget();
+  return widget ? html`<div class="side-widget" data-trust="widget"><${AgentWidget} slot="sidebar" widget=${widget} binds=${fleetBinds(app.instances, app.exec, app.awaiting)} /></div>` : null;
+}
+
 /** 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} />`;
@@ -328,7 +339,7 @@ export function DevicePrefs({ labels = false } = {}) {
 function PrefsPopover() {
   return html`<details class="prefs-pop">
     <summary class="icon-btn" aria-label=${t("app.devicePrefs")} title=${t("app.devicePrefs")}><${Icon} name="sun" /></summary>
-    <div class="pop" role="group" aria-label=${t("app.devicePrefs")}><${DevicePrefs} labels=${true} /></div>
+    <div data-trust="popover" class="pop" role="group" aria-label=${t("app.devicePrefs")}><${DevicePrefs} labels=${true} /></div>
   </details>`;
 }
 
@@ -338,7 +349,7 @@ function PrefsPopover() {
  */
 export function PanelHeader({ title, sub, children, headingRef, nav }) {
   const shell = useStore(shellStore);
-  return html`<header class=${`panel-head${shell.collapsed ? " collapsed" : ""}`}>
+  return html`<header data-trust="header" class=${`panel-head${shell.collapsed ? " collapsed" : ""}`}>
     <button type="button" id="sbOpen" class="icon-btn sb-open" onClick=${() => (narrow() ? openDrawer() : toggleSidebar())}
       aria-label=${narrow() ? t("app.openMenu") : t("app.expand")} title=${narrow() ? t("app.openMenu") : t("app.expand")} aria-controls="sidebar" aria-expanded=${shell.drawer ? "true" : "false"}><${Icon} name="menu" /></button>
     <div class="panel-title"><h1 ref=${headingRef} tabindex="-1">${title}</h1>${sub ? html`<div class="panel-sub">${sub}</div>` : null}</div>
@@ -368,12 +379,12 @@ function BottomTabs({ route, viewOnly }) {
   try { lastView = localStorage.getItem("agend_last_view"); } catch { /* none */ }
   const viewHref = route && (route.panel === "view" || route.panel === "log" || route.panel === "details") && route.instance ? viewPath(route.instance) : viewPath(lastView);
   if (viewOnly) {
-    return html`<nav class="tabs" aria-label=${t("app.menu")}>
+    return html`<nav data-trust="navigation" class="tabs" aria-label=${t("app.menu")}>
       ${tab(viewHref, "view", t("app.view"), route && route.panel === "view")}
       ${tab(signInHref(), "user", t("app.signIn"), false)}
     </nav>`;
   }
-  return html`<nav class="tabs" aria-label=${t("app.menu")}>
+  return html`<nav data-trust="navigation" class="tabs" aria-label=${t("app.menu")}>
     ${tab(chatHref, "chat", t("app.chat"), route && route.panel === "chat", anyAwaiting)}
     ${tab(NEEDS_PATH, "inbox", t("app.needsTab"), route && route.panel === "needs", (app.needs || []).length, t("app.needsCount", (app.needs || []).length))}
     ${tab(open ? detailsPath(open) : "/ui/fleet", "fleet", t("app.fleet"), route && (route.panel === "fleet" || route.panel === "details"))}
@@ -386,7 +397,7 @@ function ConnectionLine() {
   const { connection, hydration, retryHydration } = useStore(appStore);
   // A late catch-up that is not done: the chat may be missing what was open before it loaded (#1425 review).
   if (hydration === "retrying" || hydration === "failed") {
-    return html`<div class="conn" role="status">${hydration === "failed" ? t("app.hydrateFailed") : t("app.hydrating")}
+    return html`<div data-trust="status" class="conn" role="status">${hydration === "failed" ? t("app.hydrateFailed") : t("app.hydrating")}
       ${hydration === "failed" && retryHydration ? html` <button type="button" class="btn btn-sm" onClick=${() => retryHydration()}>${t("app.retry")}</button>` : null}</div>`;
   }
   if (connection === "reconnecting") return html`<${Reconnecting} />`;
@@ -400,7 +411,7 @@ function Reconnecting() {
   const { retryAt } = useStore(appStore);
   useTick(true);
   const s = typeof retryAt === "number" ? Math.max(0, Math.ceil((retryAt - NOW()) / 1000)) : 0;
-  return html`<div class="conn reconnecting" role="status">${s > 0 ? t("app.connReconnectingIn", s) : t("app.connReconnecting")}</div>`;
+  return html`<div data-trust="status" class="conn reconnecting" role="status">${s > 0 ? t("app.connReconnectingIn", s) : t("app.connReconnecting")}</div>`;
 }
 
 const NOW = () => (typeof performance !== "undefined" ? performance.now() : Date.now());
@@ -425,7 +436,7 @@ export function PendingChanges({ inline = false } = {}) {
   const list = pendingChanges || [];
   useTick(list.some(p => p.state === "pending"));
   if (!list.length) return null;
-  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">
+  return html`<div data-trust="confirmation" 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}
@@ -450,7 +461,7 @@ function OperationLine({ route }) {
     : op.phase === "posting" || op.phase === "watching" ? t("app.opApplying")
     : op.phase === "failed" ? t("app.opFailed") : restart ? t("app.opRestart") : failedRows ? t("app.opPartial") : t("app.opDone");
   const busy = op.phase === "writing" || op.phase === "posting" || op.phase === "watching";
-  return html`<div class=${`conn op-line${busy ? "" : op.phase === "failed" || restart || failedRows ? " bad" : " ok"}`} role="status">
+  return html`<div data-trust="status" class=${`conn op-line${busy ? "" : op.phase === "failed" || restart || failedRows ? " bad" : " ok"}`} role="status">
     <span>${text}</span> <a class="btn btn-sm" href=${settingsPath()}>${t("app.openSettings")}</a></div>`;
 }
 
@@ -499,7 +510,7 @@ export function Shell({ panels, onNewInstance, viewOnly = false }) {
   }, []);
   const cls = ["shell", shell.collapsed ? "sb-collapsed" : "", shell.drawer ? "sb-open" : "", shell.keyboard ? "kb-open" : ""].filter(Boolean).join(" ");
   return html`<div class=${cls}>
-    <a class="skip" href="#main">${t("app.skip")}</a>
+    <a data-trust="navigation" class="skip" href="#main">${t("app.skip")}</a>
     <${Sidebar} route=${nav.route} onNewInstance=${onNewInstance} viewOnly=${viewOnly} />
     <div class="scrim" onClick=${closeDrawer} aria-hidden="true"></div>
     <main id="main" class="main" tabindex="-1" inert=${shell.drawer && narrow() ? true : undefined}>
@@ -512,6 +523,8 @@ export function Shell({ panels, onNewInstance, viewOnly = false }) {
     ${shell.dialog ? html`<${shell.dialog.Component} ...${shell.dialog.props} onClose=${closeDialog} />` : null}
     ${viewOnly || (nav.route && nav.route.panel === "settings") ? null : html`<${PendingChanges} />`}
     <${ConfirmHost} />
+    <${ColorDialogHost} />
+    ${viewOnly ? null : html`<${OwnerCssKeepBar} />`}
     <${Toasts} />
   </div>`;
 }

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

@@ -39,6 +39,8 @@ export function applyStatus(d) {
     connections: typeof d.connections === "number" ? d.connections : null,
     // #1665: the host preferences' revision (app-prefs.js re-reads them when it moves).
     prefsRev: typeof d.prefs_rev === "number" ? d.prefs_rev : null,
+    // #1629: the agents' themes' revision (app-themes.js re-reads them when it moves).
+    themesRev: typeof d.themes_rev === "number" ? d.themes_rev : null,
     // #1685: host memory pressure slowing or holding new agents ("elevated" | "critical"), else null.
     hostMemory: d.host_memory === "elevated" || d.host_memory === "critical" ? d.host_memory : null });
 }