iobroker.assistant 1.1.0 → 1.2.0

package/build/main.js

@@ -63,6 +63,7 @@ const wyoming_1 = require("./lib/voice/wyoming");
 const esphome_1 = require("./lib/voice/esphome");
 const esphomeEntities_1 = require("./lib/voice/esphomeEntities");
 const mediaServer_1 = require("./lib/voice/mediaServer");
+const wakeWords_1 = require("./lib/voice/wakeWords");
 const tone_1 = require("./lib/voice/tone");
 const engines_1 = require("./lib/voice/engines");
 /**
@@ -70,6 +71,20 @@ const engines_1 = require("./lib/voice/engines");
  * so re-reading their whole state tree on every single request would be pure overhead.
  */
 const WEATHER_CTX_TTL = 5 * 60 * 1000;
+/**
+ * How long the NLU device model stays valid. Building it costs a `list_devices` plus a name lookup per
+ * device, and one spoken command needs it up to three times (STT hints, NLU, the cloud device list).
+ * Enum and name changes drop it at once (see {@link ListCache.onClear}); the TTL only catches devices
+ * that were added or renamed elsewhere.
+ */
+const NLU_DEVICES_TTL_MS = 60_000;
+/** Default for `localLlmTimeoutSec`: after this the local model is stopped and the next tier answers. */
+const LOCAL_LLM_TIMEOUT_SEC = 15;
+/**
+ * Answer length cap of the local model. It answers small talk and general questions, mostly by voice, and
+ * on a Raspberry Pi every token costs about a fifth of a second — 512 tokens would be a minute and a half.
+ */
+const LOCAL_LLM_MAX_TOKENS = 256;
 /**
  * The replies the assistant speaks verbatim, whatever the question was. They are pre-synthesised into
  * the TTS cache at startup; everything else is cached on first use.
@@ -163,7 +178,27 @@ function iaqLabel(value, unit, lang) {
     return lang === 'ru' ? row[3] : lang === 'de' ? row[1] : row[2];
 }
 /** NLU actions that only switch something; their success is what the confirmation tone replaces. */
-const CONTROL_ACTIONS = new Set(['on', 'off', 'level', 'color']);
+const CONTROL_ACTIONS = new Set(['on', 'off', 'level', 'color', 'volumeSet']);
+/** An intent in one line for the request trace: "level Rollo (Büro) = 30", "timerSet 300 s", "alarmSet 7:05". */
+function describeIntent(intent) {
+    let text = intent.action;
+    if (intent.device) {
+        text += ` ${intent.device.name}${intent.device.room ? ` (${intent.device.room})` : ''}`;
+    }
+    else if (intent.room) {
+        text += ` (${intent.room})`;
+    }
+    if (intent.value !== undefined) {
+        text += ` = ${JSON.stringify(intent.value)}`;
+    }
+    else if (intent.durationSec !== undefined) {
+        text += ` ${intent.durationSec} s`;
+    }
+    else if (intent.hour !== undefined) {
+        text += ` ${intent.hour}:${String(intent.minute ?? 0).padStart(2, '0')}`;
+    }
+    return text;
+}
 const FIXED_REPLIES = {
     de: ['Ok.', 'Erledigt.'],
     en: ['Okay.', 'Done.'],
@@ -200,6 +235,8 @@ class Assistant extends adapter_core_1.Adapter {
     journal = null;
     /** Short-TTL cache for the expensive device/room/function listings; invalidated on enum changes. */
     listCache = null;
+    /** The NLU device model of {@link getNluDevices}, shared by all callers (and concurrent requests). */
+    nluDevices = null;
     /** Cache of a `<base>.SET` level state id → its writable boolean sibling switch (`<base>.ON_SET`/`.ON`), or ''. */
     siblingSwitch = new Map();
     /** Tier-1a local LLM (node-llama-cpp), lazily loaded when enabled + installed; null otherwise. */
@@ -216,6 +253,10 @@ class Assistant extends adapter_core_1.Adapter {
     esphome = null;
     /** Serves spoken replies to ESPHome satellites over HTTP; null unless those are enabled. */
     media = null;
+    /** Uploaded wake words (`assistant.0/wakewords/`), offered to every ESPHome satellite. */
+    customWakeWords = new Map();
+    /** Loads {@link customWakeWords} once from the file storage; later calls wait for the same load. */
+    customWakeWordsLoaded = null;
     /** Short-term per-source conversation memory (in-memory, TTL) for follow-up questions. */
     context = new context_1.ConversationStore();
     /** Questions the assistant asked and is waiting for an answer to (`askUser`), keyed by source. */
@@ -230,6 +271,8 @@ class Assistant extends adapter_core_1.Adapter {
     mirroredTimers = new Map();
     /** Per satellite: resolves once its control objects exist, so state writes can wait for them. */
     satControlsReady = new Map();
+    /** Satellites whose `volume` state exists and is subscribed (see updateSatelliteVolume). */
+    satVolumeEnsured = new Set();
     /** Native (ioBroker) satellite state-id → sender instance id, so we can push announcements back to it. */
     nativeSatFrom = new Map();
     /** Countdown timers / reminders (roadmap #2); mirrored into `timers.*` states. Null until onReady. */
@@ -304,6 +347,9 @@ class Assistant extends adapter_core_1.Adapter {
                 allowObjectChange: cfg.allowObjectChange,
             }));
             this.listCache = new tools_1.ListCache();
+            this.listCache.onClear = () => {
+                this.nluDevices = null;
+            };
             const { tools, denied } = await (0, tools_1.buildMcpTools)(this.mcp, cfg, this.listCache, (id, fb) => this.resolveDeviceName(id, fb));
             // Let the cloud LLM handle timers/alarms too (for phrasings the rule-based NLU misses).
             tools.push(...this.buildTimerTools(), ...this.buildAlarmTools());
@@ -347,6 +393,7 @@ class Assistant extends adapter_core_1.Adapter {
                     maxTokens: cfg.maxTokens || 1024,
                     tools: tools.map(t => this.journalTool(t)),
                     log: this.log,
+                    trace: step => this.journal?.step(step),
                 });
             }
         }
@@ -434,7 +481,8 @@ class Assistant extends adapter_core_1.Adapter {
                 language,
                 stt,
                 tts,
-                answer: (question, sttMs) => this.answer(question, 'wyoming', { transport: 'wyoming', sttMs }),
+                answer: (question, sttMs, audioMs) => this.answer(question, 'wyoming', { transport: 'wyoming', sttMs, audioMs }),
+                onSpoken: info => this.reportSpoken('wyoming', info),
                 getHints: () => this.buildSttHints(),
                 log: this.log,
             });
@@ -489,6 +537,10 @@ class Assistant extends adapter_core_1.Adapter {
             this.media = null;
             return;
         }
+        await this.loadCustomWakeWords();
+        for (const word of this.customWakeWords.values()) {
+            this.serveWakeWord(word);
+        }
         this.esphome = new esphome_1.EsphomeSatellites({
             devices,
             language,
@@ -499,7 +551,10 @@ class Assistant extends adapter_core_1.Adapter {
                 room: origin.room,
                 wakeWord: origin.wakeWord,
                 sttMs: origin.sttMs,
+                audioMs: origin.audioMs,
+                vad: origin.vad,
             }),
+            onSpoken: (device, info) => this.reportSpoken(device, info),
             getHints: () => this.buildSttHints(),
             media: this.media,
             mediaHost: (cfg.esphomeMediaHost || '').trim(),
@@ -517,7 +572,15 @@ class Assistant extends adapter_core_1.Adapter {
             onEntityState: (device, room, entity) => {
                 this.updateSatelliteControl(device, room, entity).catch(e => this.log.debug(`satellite control update failed: ${e.message}`));
             },
-            expectsFollowUp: answer => this.expectsFollowUp(answer),
+            expectsFollowUp: (answer, device) => this.followUpFor(device, answer),
+            externalWakeWords: () => [...this.customWakeWords.values()].map(w => ({
+                id: w.id,
+                phrase: w.phrase,
+                languages: w.languages,
+                size: w.size,
+                sha256: w.sha256,
+                path: `${wakeWords_1.WAKE_WORD_URL_PREFIX}${w.id}.json`,
+            })),
         });
         await this.esphome.start();
         this.log.info(`ESPHome satellites: ${devices.length} device(s), STT=${cfg.sttProvider || 'openai'}, TTS=${cfg.ttsProvider || 'openai'}.`);
@@ -572,7 +635,17 @@ class Assistant extends adapter_core_1.Adapter {
                 language,
                 stt,
                 tts,
-                answer: (question, ctx) => this.answerVoice(question, ctx.device, { transport: 'udp', room: ctx.room, sttMs: ctx.sttMs }),
+                answer: (question, ctx) => this.answerVoice(question, ctx.device, {
+                    transport: 'udp',
+                    room: ctx.room,
+                    sttMs: ctx.sttMs,
+                    audioMs: ctx.audioMs,
+                }),
+                onSpoken: (device, info) => this.reportSpoken(device, info),
+                expectsFollowUp: (answer, device) => this.followUpFor(device, answer),
+                onVolume: (device, room, level) => {
+                    this.updateSatelliteVolume(device, room, level).catch(e => this.log.debug(`satellite volume update failed: ${e.message}`));
+                },
                 getHints: () => this.buildSttHints(),
                 log: this.log,
                 onStatus: (device, room, state) => {
@@ -639,6 +712,23 @@ class Assistant extends adapter_core_1.Adapter {
     expectsFollowUp(answer) {
         return /[?？]/.test(answer || '');
     }
+    /** A transport synthesised the reply to `source`'s latest request — the journal shows it with that request. */
+    reportSpoken(source, info) {
+        const cfg = this.config;
+        const provider = cfg.ttsProvider || 'openai';
+        const voices = {
+            openai: cfg.ttsVoice || 'alloy',
+            azure: cfg.azureVoice,
+            aws: cfg.awsVoice,
+            piper: cfg.piperVoice,
+        };
+        this.journal?.spoken(source, {
+            ...info,
+            provider,
+            fallback: cfg.ttsFallback || undefined,
+            voice: (voices[provider] || '').trim() || undefined,
+        });
+    }
     /** Record the origin of the current text.request/response ('' = state write, 'chat' = message, else satellite). */
     setQuerySource(source) {
         this.setStateAsync('text.querySource', { val: source, ack: true }).catch(() => { });
@@ -705,17 +795,18 @@ class Assistant extends adapter_core_1.Adapter {
                 room,
                 wakeWord: typeof msg.wakeWord === 'string' ? msg.wakeWord : undefined,
                 sttMs: Date.now() - sttStart,
+                audioMs: Math.round((pcm.length / 2 / rate) * 1000),
             });
             if (!answer) {
                 return { text, answer: '' };
             }
+            const ttsStart = Date.now();
             const reply = await engines.tts.synthesize(answer, language);
-            // Follow-up: primarily the LLM's own signal ([[LISTEN]] → lastFollowUp); "?" heuristic as fallback.
-            const llmSignalled = this.lastFollowUp;
-            const listen = llmSignalled || this.expectsFollowUp(answer);
-            if (listen) {
-                this.log.info(`→ mic-on to satellite '${source}' (${llmSignalled ? 'LLM signalled a follow-up' : 'reply is a question (fallback)'}).`);
-            }
+            this.reportSpoken(source, {
+                ms: Date.now() - ttsStart,
+                audioMs: (reply.pcm.length / 2 / reply.sampleRate) * 1000,
+            });
+            const listen = this.followUpFor(source, answer);
             return { text, answer, audio: reply.pcm.toString('base64'), sampleRate: reply.sampleRate, listen };
         }
         catch (e) {
@@ -778,6 +869,33 @@ class Assistant extends adapter_core_1.Adapter {
             await this.setStateAsync(`${base}.room`, { val: room, ack: true });
         }
     }
+    /**
+     * Mirror the playback volume a UDP satellite reported into `satellites.<id>.volume`. The state only
+     * appears for satellites that speak the `volume` message — an older one would never answer a write.
+     */
+    async updateSatelliteVolume(device, room, level) {
+        const id = await this.ensureSatelliteObjects(device, room);
+        const stateId = `satellites.${id}.volume`;
+        if (!this.satVolumeEnsured.has(id)) {
+            await this.setObjectNotExistsAsync(stateId, {
+                type: 'state',
+                common: {
+                    name: 'Playback volume',
+                    type: 'number',
+                    role: 'level.volume',
+                    unit: '%',
+                    min: 0,
+                    max: 100,
+                    read: true,
+                    write: true,
+                },
+                native: {},
+            });
+            this.subscribeStates(stateId);
+            this.satVolumeEnsured.add(id);
+        }
+        await this.setStateAsync(stateId, { val: level, ack: true });
+    }
     /**
      * Create the object tree for one satellite and return its (sanitised) state id, without touching
      * any value. Callers that only need somewhere to hang a child object use this rather than
@@ -913,11 +1031,111 @@ class Assistant extends adapter_core_1.Adapter {
             this.satWakeWordStatesEnsured.add(id);
         }
         await this.setStateAsync(`${base}.wakeWords`, { val: config.active.join(','), ack: true });
+        // `custom` marks the uploaded ones, so the settings dialog can offer to delete them.
+        const words = config.available.map(w => (this.customWakeWords.has(w.id) ? { ...w, custom: true } : w));
         await this.setStateAsync(`${base}.availableWakeWords`, {
-            val: JSON.stringify({ max: config.max, words: config.available }),
+            val: JSON.stringify({ max: config.max, words }),
             ack: true,
         });
     }
+    /** Read the uploaded wake words (`<instance>/wakewords/<id>.json` + `.tflite`) once. */
+    loadCustomWakeWords() {
+        this.customWakeWordsLoaded ||= (async () => {
+            let entries = [];
+            try {
+                entries = await this.readDirAsync(this.namespace, wakeWords_1.WAKE_WORD_DIR);
+            }
+            catch {
+                return; // nothing uploaded yet
+            }
+            for (const entry of entries) {
+                const id = entry.file.replace(/\.json$/, '');
+                if (entry.isDir || !entry.file.endsWith('.json') || !wakeWords_1.WAKE_WORD_ID_RE.test(id)) {
+                    continue;
+                }
+                try {
+                    const config = await this.readStoredFile(`${wakeWords_1.WAKE_WORD_DIR}/${id}.json`, 'utf8');
+                    const model = await this.readStoredFile(`${wakeWords_1.WAKE_WORD_DIR}/${id}.tflite`, 'binary');
+                    const word = (0, wakeWords_1.loadWakeWord)(id, config, model);
+                    this.customWakeWords.set(id, word);
+                    // Uploaded before the upload checked the model: keep it, so it can be deleted in the dialog.
+                    const problem = (0, wakeWords_1.microModelProblem)(model);
+                    if (problem) {
+                        this.log.warn(`Custom wake word ${word.phrase} (${id}) cannot run on the device: ${problem}. Delete it in the satellite settings.`);
+                    }
+                }
+                catch (e) {
+                    this.log.warn(`Custom wake word ${id} skipped: ${e.message}`);
+                }
+            }
+            if (this.customWakeWords.size) {
+                this.log.info(`Custom wake words: ${[...this.customWakeWords.values()].map(w => `${w.phrase} (${w.id})`).join(', ')}`);
+            }
+        })();
+        return this.customWakeWordsLoaded;
+    }
+    /**
+     * Read a file from this instance's file storage as a Buffer. Depending on the backend and the file's
+     * type it comes back as a Buffer or a string — `encoding` says how to read the latter.
+     */
+    async readStoredFile(name, encoding) {
+        const res = (await this.readFileAsync(this.namespace, name));
+        const f = Buffer.isBuffer(res) || typeof res === 'string' ? res : res.file;
+        if (f == null) {
+            throw new Error(`${name} not found`);
+        }
+        return Buffer.isBuffer(f) ? f : Buffer.from(f, encoding);
+    }
+    serveWakeWord(word) {
+        this.media?.serve(`${wakeWords_1.WAKE_WORD_URL_PREFIX}${word.id}.json`, word.config, 'application/json');
+        this.media?.serve(`${wakeWords_1.WAKE_WORD_URL_PREFIX}${word.id}.tflite`, word.model, 'application/octet-stream');
+    }
+    /**
+     * Store an uploaded wake word and offer it to the connected satellites. It shows up in their wake
+     * word list right away; a device downloads the model only when it is selected there.
+     */
+    async addCustomWakeWord(message) {
+        await this.loadCustomWakeWords();
+        const text = (value) => (typeof value === 'string' ? value : undefined);
+        const languages = (Array.isArray(message.languages)
+            ? message.languages.map(String)
+            : (text(message.languages) ?? '').split(/[,;\s]+/)).filter(Boolean);
+        const word = (0, wakeWords_1.prepareWakeWord)({
+            model: Buffer.from(text(message.model) ?? '', 'base64'),
+            fileName: text(message.fileName),
+            config: message.config && typeof message.config === 'object'
+                ? message.config
+                : text(message.config),
+            phrase: text(message.phrase),
+            languages,
+        }, this.config.voiceLanguage || this.language || '');
+        if (!this.customWakeWords.has(word.id)) {
+            await this.writeFileAsync(this.namespace, `${wakeWords_1.WAKE_WORD_DIR}/${word.id}.tflite`, word.model);
+            await this.writeFileAsync(this.namespace, `${wakeWords_1.WAKE_WORD_DIR}/${word.id}.json`, word.config);
+            this.customWakeWords.set(word.id, word);
+            this.serveWakeWord(word);
+            this.log.info(`Custom wake word uploaded: ${word.phrase} (${word.id}, ${word.size} bytes)`);
+        }
+        const devices = this.esphome?.refreshWakeWords() ?? 0;
+        return { id: word.id, phrase: word.phrase, languages: word.languages, size: word.size, devices };
+    }
+    /**
+     * Remove an uploaded wake word: it is no longer offered or served. A device that already downloaded
+     * it keeps its copy — the ESPHome API cannot delete a model from a device.
+     */
+    async deleteCustomWakeWord(id) {
+        await this.loadCustomWakeWords();
+        if (!wakeWords_1.WAKE_WORD_ID_RE.test(id) || !this.customWakeWords.has(id)) {
+            throw new Error(`unknown wake word ${id}`);
+        }
+        for (const ext of ['json', 'tflite']) {
+            await this.delFileAsync(this.namespace, `${wakeWords_1.WAKE_WORD_DIR}/${id}.${ext}`).catch(() => undefined);
+            this.media?.unserve(`${wakeWords_1.WAKE_WORD_URL_PREFIX}${id}.${ext}`);
+        }
+        this.customWakeWords.delete(id);
+        this.esphome?.refreshWakeWords();
+        this.log.info(`Custom wake word deleted: ${id}`);
+    }
     /**
      * Mirror everything an ESPHome satellite exposes besides the voice pipeline into
      * `satellites.<id>.controls.*` — microphone gain and volume, noise suppression, wake-word and
@@ -1281,7 +1499,8 @@ class Assistant extends adapter_core_1.Adapter {
                     await Promise.all(allowed.map(d => this.voice.announce(d, pcm, sampleRate)));
                     delivered += allowed.length;
                     if (listen) {
-                        allowed.forEach(d => this.voice.listen(d));
+                        const playMs = (pcm.length / 2 / sampleRate) * 1000;
+                        allowed.forEach(d => this.voice.listen(d, playMs));
                     }
                 }
                 catch (e) {
@@ -1630,6 +1849,15 @@ class Assistant extends adapter_core_1.Adapter {
             await this.setStateAsync('dnd', { val: this.globalDnd, ack: true });
             return;
         }
+        // Playback volume of a UDP satellite — not acked here: the satellite reports the level it took.
+        const satVolume = id.match(/\.satellites\.([^.]+)\.volume$/);
+        if (satVolume) {
+            const device = this.satDeviceById.get(satVolume[1]) || satVolume[1];
+            if (!this.voice?.volume(device, { level: Number(state.val) })) {
+                this.log.warn(`Cannot set the volume of '${device}': it is not a registered UDP satellite.`);
+            }
+            return;
+        }
         const satDnd = id.match(/\.satellites\.([^.]+)\.dnd$/);
         if (satDnd) {
             this.dndById.set(satDnd[1], !!state.val);
@@ -2014,6 +2242,41 @@ class Assistant extends adapter_core_1.Adapter {
             }
             return;
         }
+        // Settings dialog / scripts: own wake words for the ESPHome satellites (microWakeWord models).
+        // uploadWakeWord: { model: base64 .tflite, fileName?, config?: JSON text, phrase?, languages? }
+        //   → { ok, id, phrase, languages, size, devices } | { error }
+        // deleteWakeWord: { id } → { ok } | { error };  listWakeWords → { wakeWords: [{id, phrase, …}] }
+        if (obj.command === 'uploadWakeWord' || obj.command === 'deleteWakeWord' || obj.command === 'listWakeWords') {
+            const m = (obj.message || {});
+            let payload;
+            try {
+                if (obj.command === 'uploadWakeWord') {
+                    payload = { ok: true, ...(await this.addCustomWakeWord(m)) };
+                }
+                else if (obj.command === 'deleteWakeWord') {
+                    await this.deleteCustomWakeWord(typeof m.id === 'string' ? m.id : '');
+                    payload = { ok: true };
+                }
+                else {
+                    await this.loadCustomWakeWords();
+                    payload = {
+                        wakeWords: [...this.customWakeWords.values()].map(w => ({
+                            id: w.id,
+                            phrase: w.phrase,
+                            languages: w.languages,
+                            size: w.size,
+                        })),
+                    };
+                }
+            }
+            catch (e) {
+                payload = { error: e.message };
+            }
+            if (obj.callback) {
+                this.sendTo(obj.from, obj.command, payload, obj.callback);
+            }
+            return;
+        }
         // Scripts: everything an ESPHome satellite exposes besides the voice pipeline.
         // message = { device? }; without a device, every connected one is listed.
         if (obj.command === 'getControls') {
@@ -2220,6 +2483,18 @@ class Assistant extends adapter_core_1.Adapter {
             }
             return;
         }
+        // Admin chat debug view: one request with every step of its processing (message = { id }).
+        if (obj.command === 'getJournalTrace') {
+            const id = String(obj.message?.id || '');
+            const entry = this.journal?.get(id);
+            const result = entry
+                ? { entry, steps: await this.journal.trace(id) }
+                : { error: this.journal?.enabled ? 'unknown request' : 'journal disabled' };
+            if (obj.callback) {
+                this.sendTo(obj.from, obj.command, result, obj.callback);
+            }
+            return;
+        }
         if (obj.command === 'clearJournal') {
             this.journal?.clear();
             if (obj.callback) {
@@ -2271,28 +2546,92 @@ class Assistant extends adapter_core_1.Adapter {
      */
     answer(question, source = '', origin = {}) {
         return this.requestOrigin.run({ source, room: origin.room || '' }, () => this.journal
-            ? this.journal.run(question, source, origin, () => this.answerTracked(question, source))
+            ? this.journal.run(question, source, origin, () => {
+                this.traceSpeechInput(question, origin);
+                return this.answerTracked(question, source);
+            })
             : this.answerTracked(question, source));
     }
+    /** Speech recognition happened before the request: put it at the head of its trace. */
+    traceSpeechInput(question, origin) {
+        if (origin.sttMs === undefined) {
+            return;
+        }
+        const cfg = this.config;
+        const provider = cfg.sttProvider || 'openai';
+        const audio = origin.audioMs !== undefined ? `, ${(origin.audioMs / 1000).toFixed(1)} s of audio` : '';
+        this.journal?.step({
+            stage: 'stt',
+            title: `Speech recognition: ${provider}${audio}`,
+            ms: origin.sttMs,
+            data: {
+                provider,
+                fallback: cfg.sttFallback || undefined,
+                model: (cfg.sttModel || cfg.voskModel || '').trim() || undefined,
+                language: cfg.voiceLanguage || this.language || '',
+                audioMs: origin.audioMs,
+                wakeWord: origin.wakeWord,
+                vad: origin.vad,
+                transcript: question,
+            },
+        });
+    }
     async answerTracked(question, source) {
         const useCtx = this.config.useConversationContext !== false;
         const history = useCtx ? this.context.get(source) : [];
+        if (history.length) {
+            this.journal?.step({
+                stage: 'context',
+                title: `Conversation context: ${history.length} earlier turn(s) of '${source}'`,
+                data: history,
+            });
+        }
         const raw = await this.produceAnswer(question, history, source);
         // The LLM signals "I'm waiting for the user's reply" by appending the [[LISTEN]] control marker
-        // (see followUpHint). Strip it here so it's neither stored, shown nor spoken, and expose it as the
-        // follow-up flag. Single-user voice → a shared field is race-free enough (read right after await).
-        this.lastFollowUp = /\[\[LISTEN\]\]/i.test(raw);
-        if (this.lastFollowUp) {
+        // (see followUpHint). Strip it here so it's neither stored, shown nor spoken, and keep it per source:
+        // two satellites answered at the same time must not hand each other their mic-on.
+        const followUp = /\[\[LISTEN\]\]/i.test(raw);
+        this.followUps.set(source, followUp);
+        if (followUp) {
             this.journal?.note({ followUp: true });
         }
         const result = raw.replace(/\s*\[\[LISTEN\]\]\s*/gi, ' ').trim();
+        this.journal?.step({
+            stage: 'answer',
+            title: result
+                ? `Answer: ${result.length} characters${followUp ? ', waits for a reply' : ''}`
+                : 'No spoken answer',
+            data: { answer: result, raw: raw !== result ? raw : undefined, followUp },
+        });
         if (useCtx && result) {
             this.context.add(source, question, result);
         }
         return result;
     }
-    /** Whether the LAST {@link answer} asked the user something (LLM-signalled via [[LISTEN]]). */
-    lastFollowUp = false;
+    /** Per source: whether its last {@link answer} asked the user something (LLM-signalled via [[LISTEN]]). */
+    followUps = new Map();
+    /**
+     * Should the satellite behind `source` re-open its mic after this reply? Primarily the LLM's own
+     * [[LISTEN]] signal, with a question mark in the reply as the fallback (the NLU and the local tiers
+     * cannot emit the marker, but they do ask "Meinst du Büro oder Wohnzimmer?").
+     */
+    wantsFollowUp(source, answer) {
+        if (!answer) {
+            return null;
+        }
+        if (this.followUps.get(source)) {
+            return 'llm';
+        }
+        return this.expectsFollowUp(answer) ? 'question' : null;
+    }
+    /** {@link wantsFollowUp} for a voice transport, logged, as the `listen` flag of the reply. */
+    followUpFor(source, answer) {
+        const why = this.wantsFollowUp(source, answer);
+        if (why) {
+            this.log.info(`→ mic-on to satellite '${source}' (${why === 'llm' ? 'LLM signalled a follow-up' : 'reply is a question'}).`);
+        }
+        return !!why;
+    }
     /**
      * System-prompt instruction letting the LLM explicitly signal a follow-up: append [[LISTEN]] when it
      * asks the user something and waits for an answer. More reliable than a "?" heuristic and lets a
@@ -2369,6 +2708,7 @@ class Assistant extends adapter_core_1.Adapter {
             const n = this.stopRinging();
             this.log.info(`Ring stopped by voice (${n} session(s)).`);
             this.journal?.note({ tier: 'stop' });
+            this.journal?.step({ stage: 'stop', title: `Stop word: silenced ${n} ringing timer/alarm(s)` });
             const lang = String(this.config.voiceLanguage || this.language || 'en');
             return lang === 'ru' ? 'Хорошо.' : lang === 'de' ? 'Ok.' : 'Okay.';
         }
@@ -2380,6 +2720,11 @@ class Assistant extends adapter_core_1.Adapter {
             if (this.pending.deliver(source, question)) {
                 this.log.info(`Answer to "${asked}" from source '${source || 'any'}': ${question}`);
                 this.journal?.note({ tier: 'askReply', detail: asked || undefined });
+                this.journal?.step({
+                    stage: 'askReply',
+                    title: `Reply to the open question "${asked}"`,
+                    data: { question: asked, reply: question },
+                });
                 return '';
             }
         }
@@ -2390,9 +2735,17 @@ class Assistant extends adapter_core_1.Adapter {
         if (routine) {
             this.log.info(`Routine '${routine.name}' triggered (source='${source}').`);
             this.journal?.note({ tier: 'routine', detail: routine.name });
+            this.journal?.step({ stage: 'routine', title: `Routine "${routine.name}" matched`, data: routine });
             await this.runRoutine(routine, source);
             return routine.reply;
         }
+        if (this.routines.length) {
+            this.journal?.step({
+                stage: 'routine',
+                title: `No routine matched (${this.routines.length} configured)`,
+                data: { phrases: this.routines.map(r => ({ name: r.name, phrases: r.phrases })) },
+            });
+        }
         // Tier 0: rule-based NLU (device commands) — fastest, offline, free.
         if (this.config.useLocalNlu) {
             // "Spiele den Kanal X ab" first: the device NLU would find the TV in "… auf dem Fernseher" and
@@ -2401,9 +2754,19 @@ class Assistant extends adapter_core_1.Adapter {
             if (yt) {
                 this.log.info(`YouTube request understood locally: ${yt.kind} "${yt.query}" (source='${source}').`);
                 this.journal?.note({ tier: 'nlu', detail: `youtube ${yt.kind}` });
+                const start = Date.now();
                 const res = await this.playYouTube(yt.query, yt.kind, yt.player);
+                this.journal?.step({
+                    stage: 'youtube',
+                    title: `YouTube ${yt.kind} "${yt.query}"${yt.player ? ` on "${yt.player}"` : ''}`,
+                    ms: Date.now() - start,
+                    data: { parsed: yt, result: res },
+                });
                 return res.text;
             }
+            if (this.youtubePlayers.length) {
+                this.journal?.step({ stage: 'youtube', title: 'Not a YouTube command' });
+            }
             try {
                 const handled = await this.tryLocalNlu(question, source);
                 if (handled !== null) {
@@ -2413,36 +2776,49 @@ class Assistant extends adapter_core_1.Adapter {
             }
             catch (e) {
                 this.log.debug(`NLU skipped: ${e.message}`);
+                this.journal?.step({
+                    stage: 'nlu',
+                    level: 'warn',
+                    title: `NLU gave up, the request goes on: ${e.message}`,
+                    data: (0, journal_1.errorInfo)(e),
+                });
             }
         }
+        else {
+            this.journal?.step({ stage: 'nlu', title: 'Rule-based NLU is switched off (useLocalNlu)' });
+        }
         // Current weather from the configured adapter — prepended to the user turn of BOTH LLM tiers so
         // "how's the weather?" is answered from real data (the local model has no tools and would otherwise
         // invent a forecast; the cloud model saves a get_weather round-trip). Cached, see buildWeatherContext.
         const weather = await this.buildWeatherContext();
         // Tier 1a: local LLM — answers general questions offline; emits HANDOFF for anything needing tools.
+        // With a cloud LLM it only goes first when asked to (`localLlmFirst`): on a Raspberry Pi a small model
+        // needs 10–25 s, often only to hand off, and the cloud then starts from zero. By default it is the
+        // fallback for when the cloud fails (see below).
         // Skipped inside an ongoing conversation (history present): the tool-free local model gets no history,
         // so it would answer a follow-up like "yes" context-free and swallow it — let the cloud LLM (which has
         // the thread and the tools) handle follow-ups instead. Without a cloud LLM there is nobody to hand
         // follow-ups to, so the local model takes them too.
-        if (this.config.useLocalLlm && this.localLlm && (!history.length || !this.agent)) {
-            try {
-                // The local model has no tools: without these lines it would invent the weather and guess
-                // who is at home.
-                const facts = [weather, this.buildPresenceContext()].filter(Boolean).join('\n\n');
-                const ans = await this.localLlm.ask(facts ? `${facts}\n\n${question}` : question);
-                if (ans && !(0, localLlm_1.isHandoff)(ans)) {
-                    this.log.info(`Answered by local LLM (source='${source}').`);
-                    this.journal?.note({ tier: 'localLlm', detail: this.localLlmName() });
-                    return ans;
-                }
-                this.log.debug('Local LLM handed off to the cloud LLM.');
-            }
-            catch (e) {
-                this.log.debug(`Local LLM error: ${e.message}`);
+        const useLocal = !!(this.config.useLocalLlm && this.localLlm);
+        const localFirst = useLocal && (!this.agent || !!this.config.localLlmFirst);
+        if (localFirst && (!history.length || !this.agent)) {
+            const ans = await this.askLocalLlm(question, weather, source);
+            if (ans) {
+                return ans;
             }
         }
-        else if (this.config.useLocalLlm && this.localLlm) {
+        else if (localFirst) {
             this.log.debug('Local LLM skipped (follow-up in an ongoing conversation → cloud LLM).');
+            this.journal?.step({
+                stage: 'localLlm',
+                title: 'Local LLM skipped: follow-up in an ongoing conversation goes to the cloud LLM',
+            });
+        }
+        else if (useLocal) {
+            this.journal?.step({
+                stage: 'localLlm',
+                title: 'Local LLM not asked first: it is the fallback for when the cloud LLM fails (localLlmFirst)',
+            });
         }
         // Tier 2: cloud LLM with full tool access. Inject a compact device list into the system prompt so
         // the model can act without a first `list_devices` round-trip (kept cached via prompt caching).
@@ -2451,6 +2827,11 @@ class Assistant extends adapter_core_1.Adapter {
             // read out as a technical message.
             this.log.info(`No local tier could answer and no LLM provider is configured (source='${source}').`);
             this.journal?.note({ tier: 'none' });
+            this.journal?.step({
+                stage: 'none',
+                level: 'warn',
+                title: 'Nothing local understood the request and no LLM provider is configured',
+            });
             return this.localOnlyFallback();
         }
         const ctx = await this.buildDeviceContext();
@@ -2462,12 +2843,99 @@ class Assistant extends adapter_core_1.Adapter {
         this.log.info(`Cloud LLM [${this.agent.model || 'auto'}] (source='${source}', context=${history.length} turn(s)${mem ? ', memory' : ''}${weather ? ', weather' : ''}${this.presence?.configured ? ', presence' : ''}) — running tool loop…`);
         // Prepend the current date/time (and the weather line, if a source is configured) to the user turn —
         // cache-safe, see buildTimeContext. The stored history keeps the untouched question.
-        const questionForLlm = [this.buildTimeContext(), weather, question].filter(Boolean).join('\n\n');
+        const time = this.buildTimeContext();
+        const questionForLlm = [time, weather, question].filter(Boolean).join('\n\n');
         this.journal?.note({
             tier: 'cloud',
             detail: `${this.config.provider || 'openai'} · ${this.agent.model || 'auto'}`,
         });
-        return this.agent.ask(questionForLlm, sys, history);
+        // What went into the prompt, piece by piece. The device list is only counted: the model's opening
+        // step carries the whole system prompt, and with it the list.
+        const deviceLines = ctx ? ctx.split('\n').length - 1 : 0;
+        this.journal?.step({
+            stage: 'context',
+            title: `Prompt: ${deviceLines} devices${mem ? ', memory' : ''}${weather ? ', weather' : ''}${followUp ? ', follow-up marker' : ''}`,
+            data: {
+                systemPrompt: this.config.systemPrompt || '',
+                followUpHint: followUp || undefined,
+                memory: mem || undefined,
+                devices: deviceLines,
+                time,
+                weather: weather || undefined,
+            },
+        });
+        try {
+            return await this.agent.ask(questionForLlm, sys, history);
+        }
+        catch (e) {
+            // Offline, quota, outage: the local model is the fallback — unless it was already asked above.
+            if (useLocal && !localFirst) {
+                this.log.warn(`Cloud LLM failed (${e.message}) — asking the local LLM instead.`);
+                this.journal?.step({
+                    stage: 'localLlm',
+                    level: 'warn',
+                    title: `Cloud LLM failed (${e.message}) — asking the local LLM instead`,
+                });
+                const ans = await this.askLocalLlm(question, weather, source);
+                if (ans) {
+                    return ans;
+                }
+            }
+            throw e;
+        }
+    }
+    /**
+     * Ask the local model, bounded by `localLlmTimeoutSec`. Returns its answer, or null when it handed off,
+     * timed out or failed — the caller then goes on to the next tier.
+     */
+    async askLocalLlm(question, weather, source) {
+        if (!this.localLlm) {
+            return null;
+        }
+        const timeoutMs = Math.max(1, Number(this.config.localLlmTimeoutSec) || LOCAL_LLM_TIMEOUT_SEC) * 1000;
+        const name = this.localLlmName();
+        // The local model has no tools: without these lines it would invent the weather and guess who is
+        // at home.
+        const facts = [weather, this.buildPresenceContext()].filter(Boolean).join('\n\n');
+        const prompt = facts ? `${facts}\n\n${question}` : question;
+        const busy = this.localLlm.running;
+        const data = { model: name, timeoutMs, system: this.localLlm.systemPrompt(), prompt };
+        const start = Date.now();
+        try {
+            const ans = await this.localLlm.ask(prompt, timeoutMs);
+            const ms = Date.now() - start;
+            if (ans && !(0, localLlm_1.isHandoff)(ans)) {
+                this.log.info(`Answered by local LLM (source='${source}').`);
+                this.journal?.note({ tier: 'localLlm', detail: name });
+                this.journal?.step({
+                    stage: 'localLlm',
+                    title: `Local LLM ${name}: answered`,
+                    ms,
+                    data: { ...data, answer: ans },
+                });
+                return ans;
+            }
+            this.log.debug('Local LLM handed off.');
+            this.journal?.step({
+                stage: 'localLlm',
+                title: busy
+                    ? `Local LLM ${name}: busy with another question → handed off`
+                    : `Local LLM ${name}: handed off`,
+                ms,
+                data: { ...data, answer: ans },
+            });
+        }
+        catch (e) {
+            this.log.info(`Local LLM gave no answer: ${e.message}`);
+            this.journal?.step({
+                stage: 'localLlm',
+                level: 'warn',
+                title: `Local LLM ${name}: ${e.message}`,
+                ms: Date.now() - start,
+                data: { ...data, error: (0, journal_1.errorInfo)(e) },
+            });
+        }
+        return null;
     }
     /** Reply when nothing local understood the request and there is no cloud LLM (provider "none"). */
     localOnlyFallback() {
@@ -2578,35 +3046,27 @@ class Assistant extends adapter_core_1.Adapter {
         else {
             // Switched off: do not keep what was recorded while it was on.
             await fs.promises.rm(file, { force: true }).catch(() => { });
+            await fs.promises.rm((0, journal_1.traceDirFor)(file), { recursive: true, force: true }).catch(() => { });
         }
     }
-    /** Wrap the MCP connection so every state the pipeline reads or writes lands in the journal entry. */
+    /**
+     * Wrap the MCP connection so every state the pipeline reads or writes lands in the journal entry — and a
+     * call the NLU makes directly, with its result, in the request's trace.
+     */
     journalMcp(mcp) {
         return {
             listTools: () => mcp.listTools(),
-            callTool: (name, args) => {
-                this.journal?.stateAccess(name, args);
-                return mcp.callTool(name, args);
-            },
+            callTool: (name, args) => this.journal
+                ? this.journal.stateCall(name, args, () => mcp.callTool(name, args))
+                : mcp.callTool(name, args),
             close: () => mcp.close(),
         };
     }
-    /** Wrap an LLM tool so its calls (arguments, result, duration) land in the journal entry. */
+    /** Wrap an LLM tool so its calls (arguments, result, duration) land in the journal entry and its trace. */
     journalTool(tool) {
         return {
             ...tool,
-            run: async (args) => {
-                const start = Date.now();
-                try {
-                    const result = await tool.run(args);
-                    this.journal?.tool(tool.name, args, Date.now() - start, result);
-                    return result;
-                }
-                catch (e) {
-                    this.journal?.tool(tool.name, args, Date.now() - start, undefined, e.message);
-                    throw e;
-                }
-            },
+            run: args => (this.journal ? this.journal.toolCall(tool.name, args, () => tool.run(args)) : tool.run(args)),
         };
     }
     /** Short name of the local model for the journal ("qwen2.5-1.5b-instruct-q4_k_m"). */
@@ -2704,7 +3164,7 @@ class Assistant extends adapter_core_1.Adapter {
             dataDir,
             modelUrl: (this.config.localLlmModelUrl || '').trim() || localLlm_1.DEFAULT_LOCAL_MODEL_URL,
             systemPrompt: this.config.systemPrompt || '',
-            maxTokens: this.config.maxTokens || 512,
+            maxTokens: Math.min(this.config.maxTokens || LOCAL_LLM_MAX_TOKENS, LOCAL_LLM_MAX_TOKENS),
             log: this.log,
         });
         this.lastLlmPct = -1;
@@ -2737,20 +3197,56 @@ class Assistant extends adapter_core_1.Adapter {
         }
         // Timer intents match device-independently (parse() checks them first), so build the NLU even
         // when no devices are known and always try timers before bailing out.
+        const start = Date.now();
         const { rooms, devices } = await this.getNluDevices();
-        const intents = new nlu_1.Nlu(rooms, devices, this.getNluAliases()).parseAll(question);
-        if (!intents.length || !intents.every(i => this.canExecuteNlu(i, devices.length))) {
+        const aliases = this.getNluAliases();
+        const intents = new nlu_1.Nlu(rooms, devices, aliases, {
+            weather: !!(this.config.weatherInstance || '').trim(),
+        }).parseAll(question);
+        const blockers = intents.map(i => this.nluBlocker(i, devices.length));
+        this.journal?.step({
+            stage: 'nlu',
+            title: !intents.length
+                ? `NLU: nothing recognised (${devices.length} devices, ${rooms.length} rooms known)`
+                : blockers.some(Boolean)
+                    ? `NLU: ${intents.map(i => i.action).join(' + ')} — cannot run here: ${blockers.filter(Boolean).join('; ')}`
+                    : `NLU: ${intents.map(describeIntent).join(' + ')}`,
+            level: intents.length && blockers.some(Boolean) ? 'warn' : undefined,
+            ms: Date.now() - start,
+            data: {
+                devices: devices.length,
+                rooms,
+                aliases: aliases.length ? aliases : undefined,
+                intents: intents.map((intent, i) => ({ ...intent, blockedBecause: blockers[i] || undefined })),
+            },
+        });
+        if (!intents.length || blockers.some(Boolean)) {
             return null; // nothing matched, or one part cannot run here → let the LLM answer the whole thing
         }
         this.journal?.note({ tier: 'nlu', detail: intents.map(i => i.action).join(' + ') });
         const answers = [];
         let failed = false;
         for (const intent of intents) {
+            const started = Date.now();
             try {
-                answers.push(await this.executeNluIntent(intent, source));
+                const answer = await this.executeNluIntent(intent, source);
+                answers.push(answer);
+                this.journal?.step({
+                    stage: 'nlu',
+                    title: `Executed ${describeIntent(intent)}`,
+                    ms: Date.now() - started,
+                    data: { answer },
+                });
             }
             catch (e) {
                 failed = true;
+                this.journal?.step({
+                    stage: 'nlu',
+                    level: 'error',
+                    title: `${describeIntent(intent)} failed: ${e.message}${answers.length ? '' : ' → the LLM takes over'}`,
+                    ms: Date.now() - started,
+                    data: (0, journal_1.errorInfo)(e),
+                });
                 // Nothing executed yet → hand the whole utterance to the LLM. Afterwards a state has already
                 // been written and the LLM would repeat it, so report the failed part instead of bailing out.
                 if (!answers.length) {
@@ -2773,35 +3269,44 @@ class Assistant extends adapter_core_1.Adapter {
             intents.every(i => CONTROL_ACTIONS.has(i.action)) &&
             (await this.playConfirmationTone(source))) {
             this.log.debug(`NLU confirmed with a tone instead of "${answer}".`);
+            this.journal?.step({ stage: 'nlu', title: 'Confirmed with a tone instead of words', data: { answer } });
             return '';
         }
         return answer;
     }
     /**
-     * Can this intent run locally at all? Checked for **every** part of a combined command before anything
-     * is executed: a missing manager, no known devices or disabled writes send the whole utterance to the
-     * LLM (which can explain why) instead of silently doing nothing — or only half of it.
+     * Why this intent cannot run locally ('' = it can). Checked for **every** part of a combined command
+     * before anything is executed: a missing manager, no known devices or disabled writes send the whole
+     * utterance to the LLM (which can explain why) instead of silently doing nothing — or only half of it.
      */
-    canExecuteNlu(intent, deviceCount) {
+    nluBlocker(intent, deviceCount) {
         switch (intent.action) {
             case 'timerSet':
             case 'timerQuery':
             case 'timerCancel':
-                return !!this.timers;
+                return this.timers ? '' : 'timers are not running';
             case 'alarmSet':
             case 'alarmQuery':
             case 'alarmCancel':
-                return !!this.alarms;
+                return this.alarms ? '' : 'alarms are not running';
             case 'timeQuery':
             case 'dateQuery':
-                return true;
+                return '';
+            case 'weatherQuery':
+                return (this.config.weatherInstance || '').trim() ? '' : 'no weather instance configured';
+            case 'volumeSet':
+                return this.voice || this.esphome || this.nativeSatFrom.size ? '' : 'no satellites';
             default:
                 // Device intents; writes additionally require the coarse "allow control" toggle.
-                return (deviceCount > 0 &&
-                    (!['on', 'off', 'level', 'color'].includes(intent.action) || !!this.config.allowWriteStates));
+                if (!deviceCount) {
+                    return 'no devices known';
+                }
+                return ['on', 'off', 'level', 'color'].includes(intent.action) && !this.config.allowWriteStates
+                    ? 'writing states is not allowed (allowWriteStates)'
+                    : '';
         }
     }
-    /** Execute one intent that {@link canExecuteNlu} accepted, and return its spoken answer. */
+    /** Execute one intent that {@link nluBlocker} accepted, and return its spoken answer. */
     async executeNluIntent(intent, source) {
         switch (intent.action) {
             case 'timerSet':
@@ -2815,10 +3320,97 @@ class Assistant extends adapter_core_1.Adapter {
             case 'timeQuery':
             case 'dateQuery':
                 return this.executeTimeIntent(intent);
+            case 'weatherQuery':
+                return this.executeWeatherIntent(intent);
+            case 'volumeSet':
+                return this.executeVolumeIntent(intent, source);
             default:
                 return this.executeIntent(intent);
         }
     }
+    /**
+     * Speak the weather straight from the configured adapter. Throws when the report has nothing for the
+     * asked day (or the adapter has no mapper), so the question goes on to the LLM and its tool instead.
+     */
+    async executeWeatherIntent(intent) {
+        const res = await this.readWeather(this.config.weatherInstance || '');
+        if (!res.report) {
+            throw new Error(res.error || 'no weather report');
+        }
+        const lang = String(this.config.voiceLanguage || this.language || 'en');
+        const text = (0, weather_1.buildWeatherAnswer)(res.report, lang, intent.when);
+        if (!text) {
+            throw new Error(`the weather report has no data for '${intent.when || 'now'}'`);
+        }
+        return text;
+    }
+    /**
+     * Change the playback volume of a satellite: the one in the named room, else the one that heard the
+     * command. Each transport has its own knob — the native satellite's `volume` state, the media player
+     * of an ESPHome device, the `volume` message of a UDP satellite.
+     */
+    async executeVolumeIntent(intent, source) {
+        const lang = String(this.config.voiceLanguage || this.language || 'en');
+        const satId = intent.room ? this.resolveSatelliteId(intent.room) : this.announceTargetForSource(source);
+        const absolute = typeof intent.value === 'number' ? intent.value : null;
+        const delta = intent.delta || 0;
+        const next = (current) => Math.min(100, Math.max(0, Math.round(absolute ?? current + delta)));
+        // 1 процент, 2 процента, 5 процентов (11–14 take the last form).
+        const ruPercent = (n) => n % 100 > 10 && n % 100 < 20
+            ? 'процентов'
+            : n % 10 === 1
+                ? 'процент'
+                : n % 10 >= 2 && n % 10 <= 4
+                    ? 'процента'
+                    : 'процентов';
+        const confirm = (level) => lang === 'ru'
+            ? `Громкость ${level} ${ruPercent(level)}.`
+            : lang === 'de'
+                ? `Lautstärke ${level} Prozent.`
+                : `Volume ${level} percent.`;
+        if (satId) {
+            const device = this.satDeviceById.get(satId) || satId;
+            const instance = this.nativeSatFrom.get(satId);
+            if (instance) {
+                const stateId = `${instance}.volume`;
+                const current = Number((await this.getForeignStateAsync(stateId))?.val ?? 50);
+                const level = next(Number.isFinite(current) ? current : 50);
+                await this.setForeignStateAsync(stateId, level);
+                return confirm(level);
+            }
+            const player = this.esphome?.entities(device).find(e => e.kind === 'mediaPlayer');
+            if (player) {
+                const current = (player.value?.volume ?? 0.5) * 100;
+                const level = next(current);
+                if (this.esphome.setEntity(device, player.objectId, level / 100)) {
+                    return confirm(level);
+                }
+            }
+            // A UDP satellite works out a relative step itself (it knows its level) and reports the result.
+            if (this.voice?.has(device)) {
+                this.voice.volume(device, absolute !== null ? { level: absolute } : { delta });
+                if (absolute !== null) {
+                    return confirm(next(0));
+                }
+                return lang === 'ru'
+                    ? delta > 0
+                        ? 'Сделала громче.'
+                        : 'Сделала тише.'
+                    : lang === 'de'
+                        ? delta > 0
+                            ? 'Etwas lauter.'
+                            : 'Etwas leiser.'
+                        : delta > 0
+                            ? 'A bit louder.'
+                            : 'A bit quieter.';
+            }
+        }
+        return lang === 'ru'
+            ? 'Я не знаю, громкость какой колонки изменить.'
+            : lang === 'de'
+                ? 'Ich weiß nicht, bei welchem Lautsprecher ich die Lautstärke ändern soll.'
+                : "I don't know which speaker's volume to change.";
+    }
     /** Localized "this part did not work" sentence for a failed part of a combined command. */
     nluFailureText(intent) {
         const lang = String(this.config.voiceLanguage || this.language || 'en');
@@ -2868,14 +3460,36 @@ class Assistant extends adapter_core_1.Adapter {
             return [];
         }
     }
-    /** Device model for the NLU: friendly name, room, type and controls (controlType → state id). */
-    async getNluDevices() {
+    /**
+     * Device model for the NLU: friendly name, room, type and controls (controlType → state id). Cached
+     * for {@link NLU_DEVICES_TTL_MS}; requests arriving while it is being built wait for the same build.
+     */
+    getNluDevices() {
         if (!this.mcp) {
-            return { rooms: [], devices: [] };
+            return Promise.resolve({ rooms: [], devices: [] });
         }
         // Match names in the assistant's interaction language (voice language, else system) so a
         // Russian command matches Russian smartNames.
         const nluLang = (this.config.voiceLanguage || this.language || 'en');
+        const now = Date.now();
+        const hit = this.nluDevices;
+        if (hit && hit.key === nluLang && now - hit.at < NLU_DEVICES_TTL_MS) {
+            return hit.result;
+        }
+        const entry = { key: nluLang, at: now, result: this.buildNluDevices(nluLang) };
+        this.nluDevices = entry;
+        // An empty model is usually a failed build (the manager not ready yet) — don't keep it for a minute.
+        void entry.result.then(r => {
+            if (!r.devices.length && this.nluDevices === entry) {
+                this.nluDevices = null;
+            }
+        });
+        return entry.result;
+    }
+    async buildNluDevices(nluLang) {
+        if (!this.mcp) {
+            return { rooms: [], devices: [] };
+        }
         try {
             const res = await this.mcp.callTool('list_devices', { language: nluLang });
             const parsed = JSON.parse(res.text);
@@ -3507,16 +4121,30 @@ class Assistant extends adapter_core_1.Adapter {
         if (!this.config.verifyWrites || !stateId) {
             return true;
         }
-        const deadline = Date.now() + ACK_TIMEOUT_MS;
+        const start = Date.now();
+        const deadline = start + ACK_TIMEOUT_MS;
         let last;
         while (Date.now() < deadline) {
             await this.delay(ACK_POLL_MS);
             last = await this.getForeignStateAsync(stateId).catch(() => null);
             if (last?.ack && valuesMatch(last.val, expected)) {
                 this.log.debug(`write to ${stateId} confirmed by the device.`);
+                this.journal?.step({
+                    stage: 'state',
+                    title: `${stateId} confirmed by the device`,
+                    ms: Date.now() - start,
+                    data: { expected, state: last },
+                });
                 return true;
             }
         }
+        this.journal?.step({
+            stage: 'state',
+            level: 'warn',
+            title: `${stateId}: no confirmation within ${ACK_TIMEOUT_MS} ms`,
+            ms: Date.now() - start,
+            data: { expected, state: last },
+        });
         this.log.warn(`No confirmation for ${stateId} within ${ACK_TIMEOUT_MS} ms ` +
             `(last: ${JSON.stringify(last?.val)}, ack=${String(last?.ack)}). ` +
             'If this device never acknowledges, switch "Verify device feedback" off.');
@@ -4729,12 +5357,26 @@ class Assistant extends adapter_core_1.Adapter {
      */
     async runRoutine(routine, source) {
         const origin = this.announceTargetForSource(source);
-        for (const action of routine.actions) {
+        for (const [i, action] of routine.actions.entries()) {
+            const start = Date.now();
             try {
                 await this.runTriggerAction({ id: `routine:${routine.name}`, when: [] }, action, origin);
+                this.journal?.step({
+                    stage: 'routine',
+                    title: `Routine action ${i + 1}/${routine.actions.length}`,
+                    ms: Date.now() - start,
+                    data: action,
+                });
             }
             catch (e) {
                 this.log.warn(`Routine '${routine.name}': an action failed — ${e.message}`);
+                this.journal?.step({
+                    stage: 'routine',
+                    level: 'error',
+                    title: `Routine action ${i + 1}/${routine.actions.length} failed: ${e.message}`,
+                    ms: Date.now() - start,
+                    data: { action, error: (0, journal_1.errorInfo)(e) },
+                });
             }
         }
     }