smart-home-engine 2.0.1 → 3.0.0-beta.0

package/src/lib/timing.js

@@ -0,0 +1,421 @@
+'use strict';
+/**
+ * Timing helpers for scripts: debounce, throttle, a restartable timeout, retry with
+ * backoff, and the debounce/throttle of a subscription.
+ *
+ * The helpers do not touch Node's timers. They take the script's tracked timer primitives, so every
+ * pending run is cleared when the script is unloaded or hot-reloaded and shows up in the timer list
+ * with its kind and name. Errors thrown by the wrapped function propagate to the caller — the
+ * sandbox runs the timer callbacks inside the script's domain, which logs them with the script name.
+ *
+ * Units: the function helpers take milliseconds like setTimeout; the subscription options take
+ * seconds like `shift` and `random`.
+ */
+
+const { isValidDelay, describeDelay } = require('./script-timers');
+
+function assertFn(fn, api, what = 'fn') {
+    if (typeof fn !== 'function') throw new TypeError(`${api}: ${what} must be a function (got ${describeDelay(fn)})`);
+}
+
+function assertDelay(ms, api, what) {
+    if (!isValidDelay(ms)) throw new TypeError(`${api}: ${what} must be a number of milliseconds (got ${describeDelay(ms)})`);
+}
+
+/**
+ * @param {object} prim the script's primitives
+ * @param {Function} prim.setTimeout (fn, ms, meta) → id; meta is { kind, name } for the timer list
+ * @param {Function} prim.clearTimeout (id)
+ * @param {Function} [prim.now] → ms, default Date.now
+ * @param {Function} [prim.onUnload] (fn) → off(); fn runs when the script is unloaded
+ * @returns {{ debounce: Function, throttle: Function, timeout: Function, retry: Function }}
+ */
+function createTimingHelpers(prim) {
+    const { setTimeout: setTimer, clearTimeout: clearTimer } = prim;
+    const now = prim.now || Date.now;
+    const onUnload = typeof prim.onUnload === 'function' ? prim.onUnload : () => () => {};
+    // the script line a helper was created on, captured once per helper and carried in its timer meta
+    // (the stack at re-arm time points into a callback, not to the registration)
+    const lineAt = typeof prim.line === 'function' ? prim.line : () => null;
+
+    /**
+     * Bundle calls: run fn with the arguments of the last call once `wait` ms passed without a new
+     * call — at the latest `maxWait` ms after the first call of a bundle.
+     * @param {Function} fn
+     * @param {number} wait ms
+     * @param {object} [opts]
+     * @param {number} [opts.maxWait] ms; run at the latest this long after the first bundled call
+     * @param {boolean} [opts.leading=false] run on the first call of a bundle as well
+     * @param {boolean} [opts.trailing=true] run after the quiet period (with the last call's arguments)
+     * @param {boolean} [opts.flushOnUnload=false] run a pending call when the script is unloaded
+     * @param {string} [opts.name] shown in the timer list
+     * @returns {Function} wrapped(...args) with cancel(), flush(), pending()
+     */
+    function debounce(fn, wait, opts = {}) {
+        const api = 'she.debounce(fn, wait, [opts])';
+        assertFn(fn, api);
+        assertDelay(wait, api, 'wait');
+        const { leading = false, trailing = true, maxWait, flushOnUnload = false, _onSettle } = opts;
+        if (maxWait !== undefined) assertDelay(maxWait, api, 'opts.maxWait');
+        if (!leading && !trailing) throw new TypeError(`${api}: opts.leading and opts.trailing cannot both be false`);
+        const name = opts.name || fn.name || undefined;
+        const line = opts.line !== undefined ? opts.line : lineAt();
+        const meta = { kind: 'debounce', name, line };
+        const maxMeta = { kind: 'debounce maxWait', name, line };
+
+        let timer = null;
+        let maxTimer = null;
+        let lastArgs = null;
+        let waiting = false; // a call waits to run
+        let result;
+
+        function settle() {
+            lastArgs = null;
+            waiting = false;
+            if (timer === null && maxTimer === null && typeof _onSettle === 'function') _onSettle();
+        }
+        function clearTimers() {
+            if (timer !== null) clearTimer(timer);
+            if (maxTimer !== null) clearTimer(maxTimer);
+            timer = maxTimer = null;
+        }
+        function invoke() {
+            const args = lastArgs;
+            lastArgs = null;
+            waiting = false;
+            result = fn(...args);
+            if (timer === null && maxTimer === null && typeof _onSettle === 'function') _onSettle();
+            return result;
+        }
+        function onWait() {
+            timer = null;
+            if (maxTimer !== null) {
+                clearTimer(maxTimer);
+                maxTimer = null;
+            }
+            if (trailing && waiting) invoke();
+            else settle();
+        }
+        function onMaxWait() {
+            maxTimer = null;
+            if (timer !== null) {
+                clearTimer(timer);
+                timer = null;
+            }
+            if (waiting) invoke();
+            else settle();
+        }
+        function wrapped(...args) {
+            const idle = timer === null;
+            lastArgs = args;
+            if (idle && maxWait !== undefined && maxTimer === null) maxTimer = setTimer(onMaxWait, maxWait, maxMeta);
+            if (timer !== null) clearTimer(timer);
+            timer = setTimer(onWait, wait, meta);
+            if (idle && leading) invoke();
+            else waiting = true;
+            return result;
+        }
+        wrapped.cancel = () => {
+            clearTimers();
+            settle();
+        };
+        wrapped.flush = () => {
+            clearTimers();
+            if (waiting) return invoke();
+            settle();
+            return result;
+        };
+        wrapped.pending = () => waiting;
+        if (flushOnUnload) onUnload(() => wrapped.flush());
+        return wrapped;
+    }
+
+    /**
+     * Rate-limit calls: run fn at most once per `wait` ms — on the first call of a window
+     * (leading) and, when more calls came in, once more with the last arguments when the window ends
+     * (trailing).
+     * @param {Function} fn
+     * @param {number} wait ms
+     * @param {object} [opts]
+     * @param {boolean} [opts.leading=true]
+     * @param {boolean} [opts.trailing=true]
+     * @param {string} [opts.name] shown in the timer list
+     * @returns {Function} wrapped(...args) with cancel(), flush(), pending()
+     */
+    function throttle(fn, wait, opts = {}) {
+        const api = 'she.throttle(fn, wait, [opts])';
+        assertFn(fn, api);
+        assertDelay(wait, api, 'wait');
+        const { leading = true, trailing = true, _onSettle } = opts;
+        if (!leading && !trailing) throw new TypeError(`${api}: opts.leading and opts.trailing cannot both be false`);
+        const meta = { kind: 'throttle', name: opts.name || fn.name || undefined, line: opts.line !== undefined ? opts.line : lineAt() };
+
+        let timer = null;
+        let lastArgs = null;
+        let waiting = false;
+        let result;
+
+        function settle() {
+            lastArgs = null;
+            waiting = false;
+            if (timer === null && typeof _onSettle === 'function') _onSettle();
+        }
+        function invoke() {
+            const args = lastArgs;
+            lastArgs = null;
+            waiting = false;
+            result = fn(...args);
+            if (timer === null && typeof _onSettle === 'function') _onSettle();
+            return result;
+        }
+        function onWindowEnd() {
+            timer = null;
+            if (trailing && waiting) {
+                // the trailing run opens a new window, so runs stay `wait` apart
+                timer = setTimer(onWindowEnd, wait, meta);
+                invoke();
+            } else settle();
+        }
+        function wrapped(...args) {
+            lastArgs = args;
+            if (timer === null) {
+                timer = setTimer(onWindowEnd, wait, meta);
+                if (leading) invoke();
+                else waiting = true;
+            } else waiting = true;
+            return result;
+        }
+        wrapped.cancel = () => {
+            if (timer !== null) clearTimer(timer);
+            timer = null;
+            settle();
+        };
+        wrapped.flush = () => {
+            if (timer !== null) clearTimer(timer);
+            timer = null;
+            if (waiting) return invoke();
+            settle();
+            return result;
+        };
+        wrapped.pending = () => waiting;
+        return wrapped;
+    }
+
+    /**
+     * A debounce or throttle with a separate state per key. The key is the first argument of the
+     * call unless opts.key(...args) says otherwise. Idle keys are forgotten, so a wildcard
+     * subscription does not accumulate state.
+     */
+    function keyed(factory, api) {
+        return function keyedHelper(fn, wait, opts = {}) {
+            assertFn(fn, api);
+            const { key: keyFn, flushOnUnload = false, name, ...rest } = opts;
+            if (keyFn !== undefined) assertFn(keyFn, api, 'opts.key');
+            const states = new Map();
+            const forKey = (key) => {
+                let state = states.get(key);
+                if (!state) {
+                    state = factory(fn, wait, { ...rest, name: name ? `${name} ${key}` : String(key), _onSettle: () => states.delete(key) });
+                    states.set(key, state);
+                }
+                return state;
+            };
+            function wrapped(...args) {
+                const key = keyFn ? keyFn(...args) : args[0];
+                return forKey(key)(...args);
+            }
+            // without a key: every key
+            wrapped.cancel = (key) => {
+                if (key !== undefined) states.get(key)?.cancel();
+                else for (const state of [...states.values()]) state.cancel();
+            };
+            wrapped.flush = (key) => {
+                if (key !== undefined) return states.get(key)?.flush();
+                for (const state of [...states.values()]) state.flush();
+                return undefined;
+            };
+            wrapped.pending = (key) => {
+                if (key !== undefined) return states.get(key)?.pending() ?? false;
+                for (const state of states.values()) if (state.pending()) return true;
+                return false;
+            };
+            wrapped.keys = () => [...states.keys()];
+            // validate eagerly, so a wrong wait fails at load time and not on the first call
+            factory(fn, wait, { ...rest, _onSettle: undefined }).cancel();
+            if (flushOnUnload) onUnload(() => wrapped.flush());
+            return wrapped;
+        };
+    }
+    debounce.keyed = keyed(debounce, 'she.debounce.keyed(fn, wait, [opts])');
+    throttle.keyed = keyed(throttle, 'she.throttle.keyed(fn, wait, [opts])');
+
+    /**
+     * A restartable one-shot timer. It is created idle: restart() arms it, another restart() starts
+     * the delay over, cancel() disarms it.
+     * @param {number} ms
+     * @param {Function} cb
+     * @param {object} [opts]
+     * @param {string} [opts.name] shown in the timer list
+     * @returns {{ restart: Function, start: Function, cancel: Function, pending: Function, remaining: Function }}
+     */
+    function timeout(ms, cb, opts = {}) {
+        const api = 'she.timeout(ms, cb, [opts])';
+        assertDelay(ms, api, 'ms');
+        assertFn(cb, api, 'cb');
+        const meta = { kind: 'timeout', name: opts.name || cb.name || undefined, line: lineAt() };
+        let id = null;
+        let due = 0;
+        const handle = {
+            /** (Re)arm the timer; a new delay replaces the one given at creation. */
+            restart(newMs) {
+                if (newMs !== undefined) {
+                    assertDelay(newMs, 'timeout.restart([ms])', 'ms');
+                    ms = newMs;
+                }
+                if (id !== null) clearTimer(id);
+                due = now() + ms;
+                id = setTimer(
+                    () => {
+                        id = null;
+                        cb();
+                    },
+                    ms,
+                    meta,
+                );
+                return handle;
+            },
+            cancel() {
+                if (id !== null) clearTimer(id);
+                id = null;
+                return handle;
+            },
+            pending: () => id !== null,
+            remaining: () => (id === null ? 0 : Math.max(0, due - now())),
+        };
+        handle.start = handle.restart;
+        return handle;
+    }
+
+    /**
+     * Call fn until it succeeds, waiting between the attempts. fn(attempt) may return a promise.
+     * The promise resolves with fn's result; when every attempt failed it calls onFail(err, tries)
+     * and resolves with its return value, or — without onFail — rejects with the last error. A
+     * script unload stops the attempts; the promise then never settles.
+     * @param {Function} fn
+     * @param {object} [opts]
+     * @param {number} [opts.tries=3] attempts in total
+     * @param {number} [opts.delay=1000] ms before the second attempt
+     * @param {number} [opts.backoff=1] the delay is multiplied by this after each failure (2 doubles it)
+     * @param {Function} [opts.onFail] (err, tries) after the last failure
+     * @param {string} [opts.name] shown in the timer list
+     * @returns {Promise}
+     */
+    function retry(fn, opts = {}) {
+        const api = 'she.retry(fn, [opts])';
+        assertFn(fn, api);
+        const { tries = 3, delay = 1000, backoff = 1, onFail } = opts;
+        if (!Number.isInteger(tries) || tries < 1) throw new TypeError(`${api}: opts.tries must be a whole number of attempts, at least 1 (got ${describeDelay(tries)})`);
+        assertDelay(delay, api, 'opts.delay');
+        if (typeof backoff !== 'number' || !Number.isFinite(backoff) || backoff < 0) throw new TypeError(`${api}: opts.backoff must be a factor (got ${describeDelay(backoff)})`);
+        if (onFail !== undefined) assertFn(onFail, api, 'opts.onFail');
+        const name = opts.name || fn.name || undefined;
+        const line = lineAt();
+
+        let aborted = false;
+        const off = onUnload(() => {
+            aborted = true;
+        });
+        return new Promise((resolve, reject) => {
+            const attempt = (n) => {
+                if (aborted) return;
+                let p;
+                try {
+                    p = Promise.resolve(fn(n));
+                } catch (err) {
+                    p = Promise.reject(err);
+                }
+                p.then(
+                    (value) => {
+                        off();
+                        resolve(value);
+                    },
+                    (err) => {
+                        if (aborted) return;
+                        if (n >= tries) {
+                            off();
+                            if (onFail) {
+                                try {
+                                    resolve(onFail(err, n));
+                                } catch (e) {
+                                    reject(e);
+                                }
+                            } else reject(err);
+                            return;
+                        }
+                        const wait = delay * Math.pow(backoff, n - 1);
+                        setTimer(() => attempt(n + 1), wait, { kind: 'retry', name: `${name ? name + ' ' : ''}attempt ${n + 1}/${tries}`, line });
+                    },
+                );
+            };
+            attempt(1);
+        });
+    }
+
+    return { debounce, throttle, timeout, retry };
+}
+
+/**
+ * The limiter of a subscription (sub options `debounce`, `maxWait`, `throttle`, `perTopic`, `name`;
+ * seconds). Returns deliver'(topic, val, obj, objPrev, msg): events are bundled, and the callback
+ * gets the last event's topic, val, obj and msg with the objPrev from before the first bundled
+ * event — so a comparison of obj and objPrev still tells whether the value really changed.
+ * @param {object} options the subscription options
+ * @param {Function} deliver (topic, val, obj, objPrev, msg) runs the script's callback
+ * @param {object} helpers from createTimingHelpers
+ * @param {string} label the default name for the timer list (the topic)
+ * @returns {Function|null} the limited deliver, or null when the options ask for none
+ */
+function subscriptionLimiter(options, deliver, helpers, label) {
+    const api = 'she.mqtt.sub(topic, opts, cb)';
+    const seconds = (what) => {
+        const v = options[what];
+        if (v === undefined) return undefined;
+        if (!isValidDelay(v)) throw new TypeError(`${api}: opts.${what} must be a number of seconds (got ${describeDelay(v)})`);
+        return v * 1000;
+    };
+    const debounce = seconds('debounce');
+    const throttle = seconds('throttle');
+    const maxWait = seconds('maxWait');
+    if (debounce === undefined && throttle === undefined) {
+        if (maxWait !== undefined) throw new TypeError(`${api}: opts.maxWait needs opts.debounce`);
+        return null;
+    }
+    if (debounce !== undefined && throttle !== undefined) throw new TypeError(`${api}: opts.debounce and opts.throttle exclude each other`);
+    if (throttle !== undefined && maxWait !== undefined) throw new TypeError(`${api}: opts.maxWait needs opts.debounce, not opts.throttle`);
+    const perTopic = !!options.perTopic;
+    const name = options.name !== undefined ? String(options.name) : label;
+
+    const firstPrev = new Map(); // key → objPrev of the first bundled event
+    const keyOf = (topic) => (perTopic ? topic : '');
+    const run = (topic, val, obj, objPrev, msg) => {
+        const key = keyOf(topic);
+        const prev = firstPrev.has(key) ? firstPrev.get(key) : objPrev;
+        firstPrev.delete(key);
+        deliver(topic, val, obj, prev, msg);
+    };
+    let limited;
+    if (debounce !== undefined) {
+        const opts = { maxWait, name, flushOnUnload: !!options.flushOnUnload, leading: !!options.leading, trailing: options.trailing !== false };
+        limited = perTopic ? helpers.debounce.keyed(run, debounce, opts) : helpers.debounce(run, debounce, opts);
+    } else {
+        const opts = { name, leading: options.leading !== false, trailing: options.trailing !== false };
+        limited = perTopic ? helpers.throttle.keyed(run, throttle, opts) : helpers.throttle(run, throttle, opts);
+    }
+    return (topic, val, obj, objPrev, msg) => {
+        const key = keyOf(topic);
+        if (!firstPrev.has(key)) firstPrev.set(key, objPrev);
+        limited(topic, val, obj, objPrev, msg);
+    };
+}
+
+module.exports = { createTimingHelpers, subscriptionLimiter };

package/src/lib/update-channel.js

@@ -0,0 +1,152 @@
+'use strict';
+/**
+ * Which version the update check offers — by channel, from the GitHub releases.
+ *
+ * `stable` offers the newest release that is not a pre-release; `beta` offers the newest of all
+ * releases, so a beta tester gets `3.0.0-beta.1` after `3.0.0-beta.0` and `3.0.0` once it is
+ * out, and nobody is ever offered a downgrade: switching back to `stable` on a beta shows an
+ * update only when a stable release is newer than what runs. The version is installed exactly
+ * (`smart-home-engine@<version>`), so npm's dist-tags play no part — but the version has to exist
+ * on npm: a GitHub release whose npm job failed is not offered. Best-effort: every failure yields
+ * "no update known" and the reason, nothing throws.
+ */
+
+const semverCompare = require('semantic-compare');
+
+const REPO = 'hobbyquaker/she';
+const PACKAGE = 'smart-home-engine';
+const GITHUB_RELEASES = `https://api.github.com/repos/${REPO}/releases?per_page=30`;
+const NPM_REGISTRY = 'https://registry.npmjs.org';
+const CHANNELS = ['stable', 'beta'];
+
+let _fetch = (...args) => fetch(...args);
+
+/** Test hook: replace the fetch implementation. */
+function setFetch(fn) {
+    _fetch = fn;
+}
+
+/** 'stable' or 'beta'; anything else is 'stable'. */
+function normalizeChannel(channel) {
+    return CHANNELS.includes(channel) ? channel : 'stable';
+}
+
+const VERSION_RX = /^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/;
+
+/** The version of a release tag (`v3.0.0-beta.0` → `3.0.0-beta.0`), or null when it is not one. */
+function versionOfTag(tag) {
+    if (typeof tag !== 'string') return null;
+    const v = tag.replace(/^v/, '');
+    return VERSION_RX.test(v) ? v : null;
+}
+
+function isPrerelease(version) {
+    return typeof version === 'string' && version.includes('-');
+}
+
+function compare(a, b) {
+    try {
+        return semverCompare(a, b);
+    } catch {
+        return 0;
+    }
+}
+
+function newest(versions) {
+    return versions.reduce((best, v) => (best === null || compare(v, best) > 0 ? v : best), null);
+}
+
+/**
+ * The newest stable release and the newest pre-release of a GitHub release list.
+ * @param {Array<{tag_name: string, prerelease?: boolean, draft?: boolean}>} releases
+ * @returns {{ stable: string|null, prerelease: string|null }}
+ */
+function newestOf(releases) {
+    const stable = [];
+    const pre = [];
+    for (const r of Array.isArray(releases) ? releases : []) {
+        if (!r || r.draft) continue;
+        const v = versionOfTag(r.tag_name);
+        if (!v) continue;
+        (r.prerelease || isPrerelease(v) ? pre : stable).push(v);
+    }
+    return { stable: newest(stable), prerelease: newest(pre) };
+}
+
+/** The version a channel offers, given the newest releases. */
+function offeredVersion(channel, { stable, prerelease }) {
+    if (normalizeChannel(channel) === 'stable') return stable;
+    if (!stable) return prerelease;
+    if (!prerelease) return stable;
+    return compare(stable, prerelease) < 0 ? prerelease : stable;
+}
+
+async function fetchReleases() {
+    const res = await _fetch(GITHUB_RELEASES, {
+        headers: { 'Accept': 'application/vnd.github+json', 'User-Agent': `${PACKAGE} update check` },
+        signal: AbortSignal.timeout(10000),
+    });
+    if (!res.ok) throw new Error(`GitHub answered ${res.status}`);
+    return res.json();
+}
+
+async function existsOnNpm(version) {
+    const res = await _fetch(`${NPM_REGISTRY}/${PACKAGE}/${encodeURIComponent(version)}`, { signal: AbortSignal.timeout(10000) });
+    if (!res.ok) return false;
+    const data = await res.json();
+    return data && data.version === version;
+}
+
+/**
+ * Check for an update on a channel.
+ * @param {object} opts
+ * @param {string} opts.installed the running version
+ * @param {string} [opts.channel] 'stable' (default) or 'beta'
+ * @param {boolean} [opts.docker] a Docker container cannot update itself
+ * @returns {Promise<{channel: string, installed: string, stable: string|null, prerelease: string|null,
+ *   latest: string|null, latestIsPrerelease: boolean, selfUpdate: boolean, checkedAt: number, error: string|null}>}
+ *   `latest` is the version to offer — newer than `installed`, on the channel, present on npm — or null
+ */
+async function checkUpdate(opts) {
+    const channel = normalizeChannel(opts.channel);
+    const installed = String(opts.installed || '');
+    const result = {
+        channel,
+        installed,
+        stable: null,
+        prerelease: null,
+        latest: null,
+        latestIsPrerelease: false,
+        selfUpdate: !opts.docker,
+        checkedAt: Date.now(),
+        error: null,
+    };
+    let releases;
+    try {
+        releases = await fetchReleases();
+    } catch (err) {
+        result.error = `release list not available: ${err.message}`;
+        return result;
+    }
+    const found = newestOf(releases);
+    result.stable = found.stable;
+    result.prerelease = found.prerelease;
+    const candidate = offeredVersion(channel, found);
+    if (!candidate || !(compare(installed, candidate) < 0)) return result;
+    let onNpm = false;
+    try {
+        onNpm = await existsOnNpm(candidate);
+    } catch (err) {
+        result.error = `npm registry not available: ${err.message}`;
+        return result;
+    }
+    if (!onNpm) {
+        result.error = `${candidate} is released on GitHub but not published on npm`;
+        return result;
+    }
+    result.latest = candidate;
+    result.latestIsPrerelease = isPrerelease(candidate);
+    return result;
+}
+
+module.exports = { CHANNELS, PACKAGE, checkUpdate, newestOf, offeredVersion, versionOfTag, isPrerelease, normalizeChannel, setFetch };

package/src/sandbox/stdlib.js

@@ -37,6 +37,11 @@ module.exports = function (she, ctx = {}) {
         sub: (...args) => she.mqttsub(...args),
         /** Publish an MQTT message. Same signature as she.mqttpub(). */
         pub: (...args) => she.mqttpub(...args),
+        /**
+         * Publish a command and wait for the device's status to confirm it. Resolves with
+         * { val, ms, tries }; rejects with an Error carrying reason timeout | offline | superseded | unloaded.
+         */
+        command: (...args) => she.mqttcommand(...args),
         /** Get the last-known value for a topic. */
         get: (topic) => she.getValue(topic),
         /** Get a specific property from a topic's state object. */
@@ -123,6 +128,15 @@ module.exports = function (she, ctx = {}) {
          * cleared by an initial timeout on startup.
          */
         timer: function Sandbox_mqtt_timer(src, ms, target) {
+            // Swapped arguments used to become a 1 ms timer and a variable named like the number —
+            // silently, apart from Node's anonymous TimeoutNaNWarning. Fail at load instead.
+            const signature = 'she.mqtt.timer(src, ms, target)';
+            if (typeof ms !== 'number' || !Number.isFinite(ms) || ms < 0) {
+                throw new TypeError(`${signature}: ms must be a number of milliseconds (got ${typeof ms === 'string' ? JSON.stringify(ms) : String(ms)})`);
+            }
+            if (typeof target !== 'string' && typeof target !== 'function') {
+                throw new TypeError(`${signature}: target must be a topic string or a callback (got ${typeof target})`);
+            }
             const key = target;
             she.mqttsub(src, { retain: false }, (topic, val) => {
                 if (isTruthy(val)) {

package/src/web/ai-tools.js

@@ -493,7 +493,7 @@ const TOOL_DEFINITIONS = [
         function: {
             name: 'list_timers',
             description:
-                'Pending one-shot timers, intervals, schedule jobs and sun events per script with their next fire time. Use it for "why did it switch at …" and "what is still going to happen".',
+                'Pending one-shot timers, intervals, schedule jobs, sun events, timing helpers (debounce, throttle, timeout, retry) and commands waiting for confirmation (she.mqtt.command) per script with their next fire time. Use it for "why did it switch at …" and "what is still going to happen".',
             parameters: {
                 type: 'object',
                 properties: { script: { type: 'string', description: 'Substring of a script path. Empty: every script with something pending.' } },
@@ -1514,14 +1514,18 @@ function toolGetHealth(ctx = {}) {
     if (!ctx.introspect?.health) return NO_INTROSPECT;
     const h = ctx.introspect.health() || {};
     const st = ctx.introspect.stats ? ctx.introspect.stats() || {} : {};
+    const cfg = ctx.introspect.config ? ctx.introspect.config() || {} : {};
     const lines = [
-        `started: ${h.started}, mqtt: ${h.mqttConfigured ? (h.mqttConnected ? 'connected' : 'DISCONNECTED') : 'not configured'}, scripts loaded: ${h.scripts}, safe mode: ${h.safeMode ? 'YES' : 'no'}`,
+        `she ${cfg.version || 'unknown version'} — started: ${h.started}, mqtt: ${h.mqttConfigured ? (h.mqttConnected ? 'connected' : 'DISCONNECTED') : 'not configured'}, scripts loaded: ${h.scripts}, safe mode: ${h.safeMode ? 'YES' : 'no'}`,
     ];
     if (st.topics !== undefined) lines.push(`topics: ${st.topics}, messages/s: ${st.mqttMsgPerSec}, handlers: ${st.handlers}`);
     if (st.memMb !== undefined)
         lines.push(`memory: ${st.memMb} MB, cpu: ${st.cpuPercent}%, event loop: ${st.eluPercent}% utilised, lag mean ${st.elMeanMs} ms max ${st.elMaxMs} ms`);
     if (st.matterEnabled) lines.push(`matter: ${st.matterNodes} node(s), ${st.matterEndpoints} endpoint(s)`);
     if (st.dbEnabled) lines.push(`sheDB: ${st.dbDocs} document(s), ${st.dbViews} view(s)`);
+    if (st.pendingTimers !== undefined)
+        lines.push(`pending timers: ${st.pendingTimers}, failed commands since start: ${st.commandsFailed ?? 0} (she.mqtt.command: timeout or offline)`);
+    if (cfg.timezone) lines.push(`time: zone ${cfg.timezone}, locale ${cfg.locale}, holidays ${cfg.holidays || 'NOT CONFIGURED (she.time.isHoliday() is always false)'}`);
     return lines.join('\n');
 }
 
@@ -1532,7 +1536,7 @@ function toolListTimers({ script = '' } = {}, ctx = {}) {
     for (const sc of ctx.introspect.scripts()) {
         if (q && !sc.label.toLowerCase().includes(q)) continue;
         const items = [
-            ...sc.timers.map((t) => (t.every ? `interval every ${ago(t.every)}, next ${inTime(t.due)}` : `timer ${inTime(t.due)}`)),
+            ...sc.timers.map((t) => (t.every ? `interval every ${ago(t.every)}, next ${inTime(t.due)}` : `${t.kind || 'timer'}${t.name ? ` "${t.name}"` : ''} ${inTime(t.due)}`)),
             ...sc.jobs.map((j) => `schedule job ${inTime(j.next)}`),
             ...sc.sunEvents.map((e) => `${e.pattern} ${inTime(e.next)}`),
         ];

package/src/web/config-api.js

@@ -8,10 +8,11 @@ const { getConfigPath } = require('../lib/storage');
 const DEFAULT_CONFIG_PATH = getConfigPath();
 
 /**
- * Config keys that are consumed only by the frontend (no daemon restart needed).
- * All other keys require a daemon restart when changed.
+ * Config keys whose change needs no daemon restart: consumed only by the frontend, or re-read
+ * from the file by the daemon at every use (updateChannel — the update check). All other keys
+ * require a daemon restart when changed.
  */
-const FRONTEND_ONLY_KEYS = new Set(['gitAutoCommit', 'gitAutoPush', 'pinnedPackages']);
+const FRONTEND_ONLY_KEYS = new Set(['gitAutoCommit', 'gitAutoPush', 'pinnedPackages', 'updateChannel']);
 
 const router = express.Router();