dsh-web-icon-indicator 0.1.0 → 0.2.1

package/lib/index.js

@@ -1,55 +1,120 @@
 /**
-* * dsh-web-icon-indicator — Host-only plugin that mirrors the
-* current DSH session state onto the browser tab favicon. Four states:
-* `idle` (default favicon), `running` (static yellow whale),
-* `asking` (yellow/red blinking), `done` (static green whale, 5s).
-*
-* The plugin is self-contained: it reads four SVG icons from its
-* `icons/` directory (relative to the package) and serves them through a
-* static `/dsh-web-icon-indicator/<name>.svg` route on the existing webServer,
-* while injecting a small browser script that polls `/dsh-web-icon-status.json`
-* and applies the right icon to `<link rel="icon">`.
-*
-* State derivation:
-*   - `agent/status` driving events update a per-session map.
-*   - `tools/pre-execute` on `ask_user_question` flips the session into
-*     `asking`; a 3.5 s minimum hold keeps the asking icon visible even
-*     when the user answers immediately. `tools/result` lets the hold
-*     expire cleanly, restoring the actual agent status.
-*   - `agent/turn-stopping` flips `running`/`asking` into `done`.
-*   - `reconcile()` (called on every status request) watches
-*     `agents.list()` for running→idle transitions as a fallback, since
-*     `agent/status`'s idle event is not reliably delivered at turn end.
-*
-* No Client half: the browser script runs outside the sandbox by being
-* injected into the served index.html, where `document` is freely available.
-* The Cordis Client sandbox is restricted to `ctx` / `React` / `host` /
-* `styles` / `console` and intentionally cannot touch the favicon.
-*
-* Configuration object (all optional):
-*   iconsDir       Absolute directory holding idle.svg / running.svg /
-*                  asking.svg / done.svg. Defaults to `<package>/icons/`.
-*   statusPath     JSON status endpoint path. Default: `/dsh-web-icon-status.json`.
-*   iconPathPrefix URL prefix for static icon files. Default: `/dsh-web-icon-indicator`.
-*   askingHoldMs   Minimum visibility for the asking icon (ms). Default 3500.
-*   askingBlinkMs  Yellow/red switch interval for asking (ms). Default 400.
-*   doneHoldMs     How long the done icon stays before falling back to idle.
-*                  Default 5000.
-*
-* @module dsh-web-icon-indicator
-*/
+ * * dsh-web-icon-indicator — Host-only plugin that mirrors the
+ * current DSH session state onto the browser tab favicon. Four states:
+ * `idle` (default favicon), `running` (static), `asking` (blinks),
+ * `done` (static, 5s hold).
+ *
+ * Unlike a per-state-SVG icon set, this plugin ships ONE base SVG
+ * (`icons/base.svg` — the DeepSeek whale outline with a `__COLOR__`
+ * placeholder) and recolors / animates it **directly in the browser**.
+ * The injected script builds each favicon frame as a `data:image/svg+xml,…`
+ * URI by replacing the fill color (and, for animated effects, injecting a
+ * transform) on every frame. Because a favicon is a plain image, SVG CSS
+ * animations never run inside the tab, so all motion is JS-driven: each
+ * state maps to a user-configurable color + effect.
+ *
+ * State derivation (unchanged):
+ *   - `agent/status` driving events update a per-session map.
+ *   - `tools/pre-execute` on `ask_user_question` flips the session into
+ *     `asking`; a minimum hold keeps the asking effect visible even when the
+ *     user answers immediately. `tools/result` lets the hold expire cleanly.
+ *   - `session/event` on `approval/asked` / `approval/decided` pins the
+ *     session into `asking` while the agent waits on the user for a
+ *     permission decision (covers sandbox escalations too).
+ *   - `agent/turn-stopping` flips `running`/`asking` into `done`.
+ *   - `reconcile()` (on every status request) watches `agents.list()` for
+ *     running→idle transitions as a fallback.
+ *
+ * No Client half: the browser script runs outside the sandbox by being
+ * injected into the served index.html, where `document` is freely available.
+ *
+ * Configuration object (all optional):
+ *   iconsDir       Absolute directory holding base.svg. Default `<package>/icons/`.
+ *   statusPath     JSON status endpoint path. Default `/dsh-web-icon-status.json`.
+ *   iconPathPrefix URL prefix for static icon files. Default `/dsh-web-icon-indicator`.
+ *   askingHoldMs   Minimum visibility for the asking state (ms). Default 3500.
+ *   doneHoldMs     How long the done state stays before falling back to idle.
+ *                  Default 5000.
+ *   states         Per-state visual config, keyed by state name:
+ *                    states[idle]    = { effect, colors[], speed? }
+ *                    states[running] = { effect, colors[], speed? }
+ *                    states[asking]  = { effect, colors[], speed? }
+ *                    states[done]    = { effect, colors[], speed? }
+ *                  - effect: one of `static | blink | breath | rainbow | heartbeat | bounce`.
+ *                  - colors: an ARRAY of hex colors; `colors[0]` is the primary.
+ *                    `blink` uses colors[0]⇄colors[1]; `breath` breathes colors[0]⇄colors[1]
+ *                    (each derives a darker second color if omitted); `rainbow` uses
+ *                    colors[0] only as the starting hue; the rest use colors[0].
+ *                  - speed: optional per-state cycle in ms (blink toggle interval too).
+ *                    Default 1200.
+ *
+ * The whole config surface is also registered with the DSH settings service
+ * (namespace `web-icon-indicator`): validated against a schemastery schema,
+ * persisted to the profile's `settings.yaml`, and editable from
+ * 设置 → 插件 → 插件配置 in the Web GUI (see the `dsh.client` browser half).
+ * While the profile composes no settings service, the plugin keeps working
+ * exactly as before, reading the composition entry directly.
+ *
+ * @module dsh-web-icon-indicator
+ */
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import z from "@deepseek-ai/schemastery";
+import { installSettingsSection, settingsNamespace } from "@deepseek-ai/dsh-settings";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
 const DEFAULTS = Object.freeze({
   askingHoldMs: 3500,
-  askingBlinkMs: 400,
   doneHoldMs: 5000,
   statusPath: "/dsh-web-icon-status.json",
   iconPathPrefix: "/dsh-web-icon-indicator",
   iconsDir: join(__dirname, "..", "icons"),
+  // One entry per state. `colors` is an ARRAY so multi-color effects (blink,
+  // breath, rainbow) can configure as many colors as they need. `speed` is the
+  // per-state cycle length in ms (blink toggle interval too); defaults to 1200.
+  states: {
+    idle: { effect: "static", colors: ["#1a1a1a"] },
+    running: { effect: "static", colors: ["#FACC15"] },
+    asking: { effect: "blink", colors: ["#E5484D", "#FACC15"], speed: 400 },
+    done: { effect: "static", colors: ["#22A06B"] },
+  },
+});
+
+const DEFAULT_SPEED = 1200; // fallback cycle when a state omits `speed`
+const EFFECT_NAMES = ["static", "blink", "breath", "rainbow", "heartbeat", "bounce"];
+const STATE_NAMES = ["idle", "running", "asking", "done"];
+
+/**
+ * Settings namespace under which this plugin's config is registered (the
+ * `web-icon-indicator:` section of the profile's settings.yaml, surfaced in
+ * 设置 → 插件 → 插件配置). Lowercase kebab, per the settings domain's rule.
+ */
+const SETTINGS_NAMESPACE = settingsNamespace("web-icon-indicator");
+
+/**
+ * Schemastery schema mirroring `DEFAULTS`. Registered with the settings
+ * service so the config is validated, persisted, and editable from the Web
+ * settings page; resolution order is schema defaults → composition `base`
+ * → user layer (`~/.dsh/settings.yaml`).
+ */
+const STATE_CONFIG_SCHEMA = z.object({
+  effect: z.union(EFFECT_NAMES).default("static"),
+  colors: z.array(z.string()).default(["#1a1a1a"]),
+  // Missing keys are omitted by schemastery, so an absent `speed` stays
+  // unset (the browser falls back to DEFAULT_SPEED).
+  speed: z.number().min(1),
+});
+
+const CONFIG_SCHEMA = z.object({
+  askingHoldMs: z.number().min(0).default(DEFAULTS.askingHoldMs),
+  doneHoldMs: z.number().min(0).default(DEFAULTS.doneHoldMs),
+  statusPath: z.string().default(DEFAULTS.statusPath),
+  iconPathPrefix: z.string().default(DEFAULTS.iconPathPrefix),
+  iconsDir: z.string(),
+  // dict (not a four-key object): the user layer may override only some
+  // states; the plugin merges the resolved value over DEFAULTS anyway.
+  states: z.dict(STATE_CONFIG_SCHEMA).default(DEFAULTS.states),
 });
 
 /** Browser script injected into every served index.html response. */
@@ -60,13 +125,20 @@ const INJECTED_SCRIPT = `
     window.__DSH_WEB_ICON_INDICATOR__ = true;
     var ORIGINAL = null;
     var TIMER = null;
-    var ANIM = null;
-    var ANIM_STATE = null;
-    var ICONS = {};
-    var LAST_STATE = null;
+    var RAF = null;
+    var PREV_STATE = null;   // state the current animation loop was started for
+    var ANIM_START = null;   // wall-clock start of the current loop (hidden-tab fallback)
     var STATUS_PATH = "__STATUS_PATH__";
-    var ICON_PREFIX = "__ICON_PREFIX__";
-    var ASKING_BLINK_MS = __ASKING_BLINK_MS__;
+    var BASE_PATH = "__BASE_PATH__";
+    var CFG = __CFG__;          // { states: { idle:{effect,colors,speed}, running:…, asking:…, done:… } }
+    var CFG_JSON = null;        // serialized states last seen; null = not synced yet
+    var BASE = null;            // base.svg text; __COLOR__ replaced per frame
+    var RE = /__COLOR__/g;
+    var DEF_SPEED = 1200;       // per-state cycle fallback when speed is omitted
+    var DEF_COLOR = "#1a1a1a";  // fallback primary color when a state has no colors
+
+    // Whale geometry (used as the transform pivot for scale/translate effects).
+    var CX = 27.889625, CY = 24.952640;
 
     function captureOriginal() {
       var link = document.querySelector("link[rel='icon']");
@@ -76,50 +148,179 @@ const INJECTED_SCRIPT = `
       var link = document.querySelector("link[rel='icon']");
       if (link && ORIGINAL) { link.setAttribute("href", ORIGINAL.href); if (ORIGINAL.type) link.setAttribute("type", ORIGINAL.type); }
     }
+    function linkEl() { return document.querySelector("link[rel='icon']"); }
     function setHref(uri) {
-      var link = document.querySelector("link[rel='icon']");
+      var link = linkEl();
       if (!link) return;
       try { link.setAttribute("href", uri); link.setAttribute("type", "image/svg+xml"); } catch (e) {}
     }
-    function iconUri(name) {
-      if (ICONS[name]) return Promise.resolve(ICONS[name]);
-      return fetch(location.origin + ICON_PREFIX + "/" + name + ".svg?t=" + Date.now(), { cache: "no-store" })
-        .then(function (r) { if (!r.ok) throw new Error("icon " + r.status); return r.text(); })
-        .then(function (txt) { ICONS[name] = "data:image/svg+xml," + encodeURIComponent(txt); return ICONS[name]; })
-        .catch(function () { return null; });
+
+    // ---- color helpers ------------------------------------------------------
+    function hexToRgb(h) {
+      h = String(h).replace('#', '');
+      if (h.length === 3) h = h.charAt(0)+h.charAt(0)+h.charAt(1)+h.charAt(1)+h.charAt(2)+h.charAt(2);
+      var n = parseInt(h, 16);
+      return [(n>>16)&255, (n>>8)&255, n&255];
+    }
+    function rgbToHex(r, g, b) {
+      return '#' + [r, g, b].map(function (v) {
+        v = Math.round(v); if (v < 0) v = 0; if (v > 255) v = 255;
+        return ('0' + v.toString(16)).slice(-2);
+      }).join('');
+    }
+    function mix(a, b, t) {
+      var ca = hexToRgb(a), cb = hexToRgb(b);
+      return rgbToHex(ca[0]+(cb[0]-ca[0])*t, ca[1]+(cb[1]-ca[1])*t, ca[2]+(cb[2]-ca[2])*t);
+    }
+    function hslToHex(h, s, l) {
+      h = ((h % 360) + 360) % 360; s /= 100; l /= 100;
+      var c = (1 - Math.abs(2*l - 1)) * s, x = c * (1 - Math.abs((h/60)%2 - 1)), m = l - c/2, r = 0, g = 0, b = 0;
+      if (h < 60) { r = c; g = x; } else if (h < 120) { r = x; g = c; } else if (h < 180) { g = c; b = x; }
+      else if (h < 240) { g = x; b = c; } else if (h < 300) { r = x; b = c; } else { r = c; b = x; }
+      return rgbToHex((r+m)*255, (g+m)*255, (b+m)*255);
+    }
+    function hueOf(hex) {
+      var c = hexToRgb(hex).map(function (v) { return v/255; });
+      var max = Math.max.apply(null, c), min = Math.min.apply(null, c), d = max - min, h = 0;
+      if (d) {
+        if (max === c[0]) h = ((c[1] - c[2]) / d) % 6;
+        else if (max === c[1]) h = (c[2] - c[0]) / d + 2;
+        else h = (c[0] - c[1]) / d + 4;
+        h *= 60; if (h < 0) h += 360;
+      }
+      return h;
+    }
+
+    // ---- svg frame builder --------------------------------------------------
+    // Reuses the fetched base template; replaces its __COLOR__ token (and,
+    // for scale/translate effects, wraps the whale in a <g transform>).
+    function frameUri(fill, effect, t, speed) {
+      if (!BASE) return null;
+      var inner = BASE.replace(RE, fill);
+      if (effect === "heartbeat" || effect === "bounce") {
+        var gattr = "";
+        if (effect === "heartbeat") {
+          var tt = (t % speed) / speed;
+          var s = 1;
+          if (tt < 0.12) s = 1 + 0.16 * Math.sin(tt / 0.12 * Math.PI);
+          else if (tt < 0.25) s = 1 + 0.10 * Math.sin((tt - 0.12) / 0.13 * Math.PI);
+          gattr = 'transform="translate(' + CX + ' ' + CY + ') scale(' + s + ') translate(' + (-CX) + ' ' + (-CY) + ')"';
+        } else {
+          var dy = -Math.abs(Math.sin((t / speed) * 2 * Math.PI * 1.6)) * 6;
+          gattr = 'transform="translate(0 ' + dy.toFixed(2) + ')"';
+        }
+        inner = inner.replace('<path id="p"', '<g ' + gattr + '><path id="p"');
+        inner = inner.replace('</svg>', '</g></svg>');
+      }
+      return "data:image/svg+xml," + encodeURIComponent(inner);
     }
-    function stopAnim() { if (ANIM) { clearInterval(ANIM); ANIM = null; } ANIM_STATE = null; }
+
+    // Consume a state's colors[] per effect. colors[0] is the primary color;
+    // multi-color effects read more entries and derive a fallback when absent.
+    function frameColor(cols, effect, t, speed) {
+      var c0 = cols[0] || DEF_COLOR;
+      var c1 = cols[1] || mix(c0, "#000000", 0.35); // derived second color if not provided
+      switch (effect) {
+        case "blink":
+          return ((t / speed) >> 0) % 2 === 0 ? c0 : c1;
+        case "breath": {
+          var k = 0.5 + 0.5 * Math.sin((t / speed) * 2 * Math.PI);
+          return mix(c0, c1, k);
+        }
+        case "rainbow":
+          return hslToHex(hueOf(c0) + (t / speed) * 360, 70, 58);
+        default:
+          return c0;
+      }
+    }
+
+    // ---- effects loop -------------------------------------------------------
+    function stateCfg(state) { return (CFG.states && CFG.states[state]) || {}; }
+    function isStatic(state) { return (stateCfg(state).effect || "static") === "static"; }
+    function frameAt(state, t) {
+      var st = stateCfg(state);
+      var effect = st.effect || "static";
+      var speed = st.speed || DEF_SPEED;
+      var cols = (st.colors && st.colors.length) ? st.colors : [DEF_COLOR];
+      return frameUri(frameColor(cols, effect, t, speed), effect, t, speed);
+    }
+    function stopAnim() { if (RAF) { cancelAnimationFrame(RAF); RAF = null; } }
     function apply(state) {
-      var link = document.querySelector("link[rel='icon']");
+      var link = linkEl();
       if (!link) return;
-      LAST_STATE = state;
-      if (state === "idle" || state == null) { stopAnim(); restore(); return; }
-      if (state === "asking") {
-        if (ANIM_STATE === "asking") return;
-        stopAnim();
-        ANIM_STATE = "asking";
-        Promise.all([iconUri("running"), iconUri("asking")]).then(function (uris) {
-          if (!uris[0] || !uris[1] || !link.isConnected) return;
-          var i = 0;
-          setHref(uris[i]);
-          ANIM = setInterval(function () { i = 1 - i; setHref(uris[i]); }, ASKING_BLINK_MS);
-        });
+      if (state == null) { stopAnim(); return; }
+      // Unchanged state: keep the running loop (don't reset the phase) — the
+      // 1 s poll would otherwise restart animated effects from phase 0 every
+      // second. Browsers PAUSE requestAnimationFrame in hidden tabs, so a
+      // background tab would freeze on the last frame: repaint here instead —
+      // animated states get a wall-clock frame (coarse ~1 Hz animation), static
+      // states repaint (self-heal / pick up changes that happened while hidden).
+      if (BASE && state === PREV_STATE) {
+        if (isStatic(state)) {
+          var sframe = frameAt(state, 0);
+          if (sframe && link.isConnected) setHref(sframe);
+        } else if (ANIM_START !== null) {
+          var aframe = frameAt(state, Date.now() - ANIM_START);
+          if (aframe && link.isConnected) setHref(aframe);
+        }
         return;
       }
+      PREV_STATE = state;
       stopAnim();
-      iconUri(state).then(function (uri) { if (uri && link.isConnected) setHref(uri); });
+      if (!BASE) { // base.svg not loaded yet — fetch once, then start
+        fetch(location.origin + BASE_PATH + "?t=" + Date.now(), { cache: "no-store" })
+          .then(function (r) { if (!r.ok) throw new Error("base " + r.status); return r.text(); })
+          .then(function (txt) { BASE = txt; PREV_STATE = null; apply(state); })
+          .catch(function () {});
+        return;
+      }
+      var t0 = null;
+      ANIM_START = Date.now();
+      // Paint the first frame synchronously so a state change shows even when
+      // rAF never fires (e.g. the tab is hidden); the rAF loop then takes over
+      // and drives the effect when the tab is visible.
+      var initial = frameAt(state, 0);
+      if (initial && link.isConnected) setHref(initial);
+      // rAF drives every effect. For "static" we paint one frame and stop;
+      // animated effects keep looping.
+      var step = function (now) {
+        if (t0 === null) t0 = now;
+        var uri = frameAt(state, now - t0);
+        if (uri && link.isConnected) setHref(uri);
+        if (isStatic(state)) return; // single frame, no loop
+        RAF = requestAnimationFrame(step);
+      };
+      RAF = requestAnimationFrame(step);
+    }
+    // Live config sync: the status response carries the current per-state
+    // visual config (the "states" field). When it differs from what this tab
+    // renders, swap it in and reset the animation phase so the next apply()
+    // repaints from scratch — a settings-card save takes effect within one
+    // poll tick, no tab reload needed. A response without "states" (older
+    // host) leaves the baked __CFG__ in place.
+    function syncCfg(j) {
+      if (!j || typeof j.states !== "object" || j.states === null) return;
+      var next = JSON.stringify(j.states);
+      if (next === CFG_JSON) return;
+      CFG_JSON = next;
+      CFG = { states: j.states };
+      PREV_STATE = null; // force a full repaint on the next apply
     }
     function poll() {
       fetch(location.origin + STATUS_PATH, { cache: "no-store" })
         .then(function (r) { if (!r.ok) throw new Error("bad"); return r.json(); })
-        .then(function (j) { apply(j.state || "idle"); })
-        .catch(function () { stopAnim(); restore(); if (TIMER) { clearInterval(TIMER); TIMER = null; } });
+        .then(function (j) { syncCfg(j); apply(j.state || "idle"); })
+        // Transient failures (host restarting, network blip) must NOT kill the
+        // poll: restore the original icon and retry on the next tick. The SPA
+        // reconnects in place, so the tab survives a host restart — the icon
+        // has to come back on its own once the endpoint returns.
+        .catch(function () { stopAnim(); restore(); });
     }
     captureOriginal();
     TIMER = setInterval(poll, 1000);
     poll();
     window.addEventListener("beforeunload", function () { stopAnim(); if (TIMER) clearInterval(TIMER); restore(); });
-  } catch ( e) {}
+  } catch (e) { }
 })();
 `;
 
@@ -143,26 +344,81 @@ export default {
   inject: ["webServer", "timer", "agents", "fs", "sandboxPolicy"],
   config: {
     askingHoldMs: DEFAULTS.askingHoldMs,
-    askingBlinkMs: DEFAULTS.askingBlinkMs,
     doneHoldMs: DEFAULTS.doneHoldMs,
     statusPath: DEFAULTS.statusPath,
     iconPathPrefix: DEFAULTS.iconPathPrefix,
     iconsDir: undefined,
+    states: DEFAULTS.states,
   },
+  /** Settings namespace + validation schema (exported for reuse/tooling). */
+  SETTINGS_NAMESPACE,
+  CONFIG_SCHEMA,
   apply(ctx) {
-    const cfg = { ...DEFAULTS, ...(ctx.get("config") || {}) };
+    const entry = ctx.get("config") || {};
+    let source = () => entry;
+    // Merge each configured state over its default: { effect, colors, speed }.
+    // Idempotent on schema-resolved values, so it doubles as the fallback
+    // normalization when the profile composes no settings service.
+    const resolveConfig = (raw) => {
+      const stateConfigs = {};
+      for (const name of STATE_NAMES) {
+        const merged = { ...(DEFAULTS.states[name] || {}), ...(raw.states?.[name] || {}) };
+        // Guard against unknown effect names: fall back to "static" so the
+        // browser never spins a pointless frame loop on a typo.
+        if (merged.effect && EFFECT_NAMES.indexOf(merged.effect) === -1) merged.effect = "static";
+        // colors: coerce a lone string into an array, drop invalid hex values,
+        // and fall back to the state default when nothing valid remains.
+        let cols = merged.colors;
+        if (typeof cols === "string") cols = [cols];
+        if (!Array.isArray(cols)) cols = [];
+        cols = cols.filter((c) => typeof c === "string" && /^#[0-9a-fA-F]{3,6}$/.test(c.trim()));
+        merged.colors = cols.length ? cols : [...(DEFAULTS.states[name]?.colors || ["#1a1a1a"])];
+        // speed: must be a positive number; otherwise use the default (1200).
+        if (typeof merged.speed !== "number" || !(merged.speed > 0)) delete merged.speed;
+        stateConfigs[name] = merged;
+      }
+      return { ...DEFAULTS, ...raw, states: stateConfigs };
+    };
+    let cfg = resolveConfig(entry);
+    // The injected script bakes config at injection time; rebuild it whenever
+    // the settings section changes so the NEXT page load picks the new values
+    // up (reload the tab — same contract as before this registration).
+    const buildScript = (c) => INJECTED_SCRIPT
+      .replace("__STATUS_PATH__", c.statusPath)
+      .replace("__BASE_PATH__", c.iconPathPrefix + "/base.svg")
+      .replace("__CFG__", JSON.stringify({ states: c.states }));
+    let script = buildScript(cfg);
+    let iconsDir = resolveIconsDir(cfg.iconsDir);
+    installSettingsSection(ctx, SETTINGS_NAMESPACE, CONFIG_SCHEMA, entry, {
+      setSource: (next) => { source = next; },
+      onChange: () => {
+        // Settings service mounted, or the section changed: re-resolve, then
+        // mutate cfg in place so the state-machine closures (asking/done hold)
+        // and the injected script see the new values immediately.
+        const next = resolveConfig(source());
+        cfg.askingHoldMs = next.askingHoldMs;
+        cfg.doneHoldMs = next.doneHoldMs;
+        cfg.statusPath = next.statusPath;
+        cfg.iconPathPrefix = next.iconPathPrefix;
+        if (next.iconsDir !== undefined) cfg.iconsDir = next.iconsDir;
+        cfg.states = next.states;
+        iconsDir = resolveIconsDir(cfg.iconsDir);
+        script = buildScript(cfg);
+      },
+    });
     const webServer = ctx.webServer;
     const agents = ctx.agents;
     const fs = ctx.fs;
     const sp = ctx.sandboxPolicy;
-    const iconsDir = resolveIconsDir(cfg.iconsDir);
     const lastSeen = new Map();
+    void sp; // sandboxPolicy injection is currently unused — reserved for future file-access policy
 
     // -- State machine -------------------------------------------------------
     const states = new Map();        // agentId -> { state, since }
     const asking = new Set();        // agentIds whose icon is currently pinned to asking
     const askDone = new Set();       // agentIds whose ask_user_question tool call already returned
     const askTimers = new Map();     // agentId -> ctx.timer.timeout disposer
+    const pendingApprovals = new Set(); // agentIds with an open approval/asked (waiting on the user)
 
     const setState = (id, state) => {
       const prev = states.get(id);
@@ -237,27 +493,60 @@ export default {
       }
     });
 
+    // Approval waits (sandbox interceptions, permission prompts): the agent
+    // blocks on the user for an `approval/asked` decision, so pin the session
+    // into `asking` exactly like ask_user_question.
+    ctx.on("session/event", (session, event) => {
+      const id = session?.id ?? event?.sessionId ?? null;
+      if (id == null || !event || (event.type !== "approval/asked" && event.type !== "approval/decided")) return;
+      if (event.type === "approval/asked") {
+        if (pendingApprovals.has(id)) return;
+        pendingApprovals.add(id);
+        asking.add(id);
+        askDone.delete(id);
+        setState(id, "asking");
+      } else {
+        if (!pendingApprovals.has(id)) return;
+        pendingApprovals.delete(id);
+        asking.delete(id);
+        const live = agents.get(id);
+        setState(id, live && live.status === "running" ? "running" : "idle");
+      }
+    });
+
     ctx.on("agent/disposed", (payload) => {
       const id = payload.agent?.id ?? null;
       if (id == null) return;
       states.delete(id);
       asking.delete(id);
       askDone.delete(id);
+      pendingApprovals.delete(id);
       lastSeen.delete(id);
       const t = askTimers.get(id);
       if (t) { try { t(); } catch (e) {} askTimers.delete(id); }
     });
 
-    // Reconcile running->idle transitions on every status request. The
-    // `agent/status` event's idle delivery is not guaranteed, so polling
-    // agents.list() is the authoritative fallback.
+    // Authoritative pending-approval check: fold the live session's event log
+    // for an `approval/asked` that no `approval/decided` has closed.
+    const hasPendingApproval = (live) => {
+      const events = live?.session?.events;
+      if (!Array.isArray(events)) return false;
+      const open = new Set();
+      for (const ev of events) {
+        if (ev.type === "approval/asked") open.add(ev.data?.id);
+        else if (ev.type === "approval/decided") open.delete(ev.data?.id);
+      }
+      return open.size > 0;
+    };
+
+    // Reconcile running->idle transitions on every status request.
     const reconcile = () => {
       for (const a of agents.list()) {
         const id = a.id;
         const st = a.status;
         const prev = lastSeen.get(id);
         lastSeen.set(id, { status: st, at: Date.now() });
-        if (asking.has(id)) continue;
+        if (asking.has(id) || hasPendingApproval(a)) continue;
         if (prev?.status === "running" && st === "idle") {
           setState(id, "done");
         } else if (st === "idle" && !states.has(id)) {
@@ -273,7 +562,7 @@ export default {
     const agentStateOf = (id) => {
       const live = agents.get(id);
       if (!live) return null;
-      if (asking.has(id)) return "asking";
+      if (asking.has(id) || hasPendingApproval(live)) return "asking";
       return live.status === "running" ? "running" : "idle";
     };
 
@@ -298,6 +587,10 @@ export default {
     };
 
     // -- Routes --------------------------------------------------------------
+    // The status endpoint also echoes the current per-state visual config
+    // (`states`): the injected script syncs it on every poll, so a settings
+    // save changes the favicon within ~1 s without a tab reload. `no-store`
+    // keeps every poll reading the freshest config.
     ctx.effect(() => webServer.register({
       kind: "exact",
       path: cfg.statusPath,
@@ -305,10 +598,11 @@ export default {
         res.statusCode = 200;
         res.setHeader("Content-Type", "application/json; charset=utf-8");
         res.setHeader("Cache-Control", "no-store");
-        res.end(JSON.stringify(aggregate()));
+        res.end(JSON.stringify({ ...aggregate(), states: cfg.states }));
       },
     }));
 
+    // Serve ONLY the base template (base.svg). The browser recolors/animate it.
     ctx.effect(() => webServer.register({
       kind: "prefix",
       path: cfg.iconPathPrefix,
@@ -316,7 +610,7 @@ export default {
         let pathname = "/";
         try { pathname = new URL(String(req?.url ?? "/"), "http://x").pathname; } catch (e) {}
         const name = pathname.replace(/^\/[^/]+\//, "");
-        if (!/^(idle|running|asking|done)\.svg$/.test(name)) {
+        if (!/^base\.svg$/.test(name)) {
           res.statusCode = 404;
           res.setHeader("Content-Type", "text/plain; charset=utf-8");
           res.end("bad name: " + name);
@@ -345,11 +639,9 @@ export default {
     }));
 
     // -- Script injection ----------------------------------------------------
-    const script = INJECTED_SCRIPT
-      .replace("__STATUS_PATH__", cfg.statusPath)
-      .replace("__ICON_PREFIX__", cfg.iconPathPrefix)
-      .replace("__ASKING_BLINK_MS__", String(cfg.askingBlinkMs));
-
+    // `script` is rebuilt by the settings onChange hook; the tapIndex closure
+    // reads the current value on every request, so a settings edit reaches the
+    // next page load without a server restart.
     ctx.effect(() => webServer.tapIndex((html) => {
       if (html.indexOf("window.__DSH_WEB_ICON_INDICATOR__") !== -1) return html;
       const tag = `<script id="dsh-web-icon-indicator">${script}<\/script>`;
@@ -357,4 +649,4 @@ export default {
       return html + tag;
     }));
   },
-};
+};

package/lib/types/client/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Browser half of dsh-web-icon-indicator (dsh.client bundle).
+ *
+ * Registers one card into the shared plugin-configuration surface
+ * (`settings.plugin.item` slot, keyed by the `web-icon-indicator` settings
+ * namespace). The card is inert unless the host serves the namespace, which
+ * the dispatching tab (`dsh-client-ui-settings-plugins`) checks for us.
+ */
+
+/** Cordis services this browser plugin injects. */
+export declare const inject: readonly ["slots", "settingsScope", "locale"];
+
+/** Mount the settings card for the `web-icon-indicator` namespace. */
+export declare function apply(ctx: unknown): void;