iobroker.assistant 1.0.3 → 1.2.0

package/build/main.js

@@ -36,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const os = __importStar(require("node:os"));
 const fs = __importStar(require("node:fs"));
 const node_child_process_1 = require("node:child_process");
+const node_async_hooks_1 = require("node:async_hooks");
 const adapter_core_1 = require("@iobroker/adapter-core");
 const path = __importStar(require("node:path"));
 const mcp_server_1 = require("@iobroker/mcp-server");
@@ -54,6 +55,7 @@ const ask_1 = require("./lib/ask");
 const presence_1 = require("./lib/presence");
 const targets_1 = require("./lib/targets");
 const routines_1 = require("./lib/routines");
+const youtube_1 = require("./lib/youtube");
 const notifications_1 = require("./lib/notifications");
 const triggers_1 = require("./lib/triggers");
 const voiceServer_1 = require("./lib/voice/voiceServer");
@@ -61,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");
 /**
@@ -68,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.
@@ -75,6 +92,12 @@ const WEATHER_CTX_TTL = 5 * 60 * 1000;
 /** How long to wait for a device to confirm a write, and how often to look. */
 const ACK_TIMEOUT_MS = 2000;
 const ACK_POLL_MS = 150;
+/** How long a TV may take to report "on" after it was switched on for YouTube. */
+const TV_POWER_TIMEOUT_MS = 30_000;
+/** How long youtube-remote may take to acknowledge a play command (it goes through Google's lounge). */
+const YOUTUBE_ACK_TIMEOUT_MS = 8000;
+/** Pause before the play command is repeated once on a TV that just booted. */
+const YOUTUBE_RETRY_MS = 5000;
 /**
  * Did the device end up with the value we asked for? Compared loosely: a dimmer told `30` may report
  * `30.0`, a switch told `true` may report `1`, and a lamp told 100 % may settle at 99 % — insisting on
@@ -155,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.'],
@@ -192,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. */
@@ -208,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. */
@@ -222,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. */
@@ -248,6 +299,13 @@ class Assistant extends adapter_core_1.Adapter {
     routines = [];
     /** Named announcement targets (roadmap B2): groups of rooms and people, from the configuration. */
     announceTargets = [];
+    /** YouTube players from the configuration; the first one is the default. */
+    youtubePlayers = [];
+    /**
+     * Where the request being answered came from, for the LLM tools: a tool only gets the model's
+     * arguments, but "play X" from the bedroom satellite should go to the bedroom TV.
+     */
+    requestOrigin = new node_async_hooks_1.AsyncLocalStorage();
     /** Who is at home (roadmap B1); mirrored into `presence.*`. Null until onReady. */
     presence = null;
     /** Satellites currently set to Do-Not-Disturb, by state id (mirrors `satellites.<id>.dnd`). */
@@ -289,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());
@@ -302,6 +363,18 @@ class Assistant extends adapter_core_1.Adapter {
                 // Only useful with satellites: without voice there is nothing to speak on.
                 tools.push(this.buildAnnounceTool());
             }
+            this.youtubePlayers = (0, youtube_1.parsePlayerRows)(cfg.youtubePlayers);
+            if (this.youtubePlayers.length) {
+                // Before the tools are built: their descriptions carry the player names, which an instance
+                // row only gets from its device.
+                for (const player of this.youtubePlayers) {
+                    if (!(await this.resolveYouTubePlayer(player))) {
+                        this.log.warn(`YouTube: ${player.instance} has no paired TV yet — pair one in its settings.`);
+                    }
+                }
+                tools.push(...this.buildYouTubeTools());
+                this.log.info(`YouTube players: ${this.youtubePlayers.map(p => p.name).join(', ')}.`);
+            }
             this.log.info(`ioBroker tools enabled (${tools.length}): ${tools.map(t => t.name).join(', ')}`);
             if (denied.length) {
                 this.log.debug(`Tools denied by access settings: ${denied.join(', ')}`);
@@ -320,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),
                 });
             }
         }
@@ -407,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,
             });
@@ -462,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,
@@ -472,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(),
@@ -490,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'}.`);
@@ -545,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) => {
@@ -612,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(() => { });
@@ -678,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) {
@@ -751,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
@@ -886,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
@@ -1254,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) {
@@ -1603,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);
@@ -1929,6 +2184,27 @@ class Assistant extends adapter_core_1.Adapter {
             }
             return;
         }
+        // Scripts: find and play something on a configured YouTube player, the TV switched on first.
+        // message = { query, kind?: 'channel'|'video'|'playlist', player? } → { ok, text, title?, id?, player? }
+        // Settings: the "Player" column of the YouTube table (selectSendTo).
+        if (obj.command === 'getYouTubeInstances') {
+            const list = await this.getYouTubeInstances();
+            if (obj.callback) {
+                this.sendTo(obj.from, obj.command, list, obj.callback);
+            }
+            return;
+        }
+        if (obj.command === 'playYouTube') {
+            const m = (obj.message || {});
+            const kind = m.kind === 'channel' || m.kind === 'playlist' || m.kind === 'video' ? m.kind : 'auto';
+            const res = String(m.query || '').trim()
+                ? await this.playYouTube(String(m.query).trim(), kind, m.player)
+                : { ok: false, text: 'no query given' };
+            if (obj.callback) {
+                this.sendTo(obj.from, obj.command, this.youtubeResultData(res), obj.callback);
+            }
+            return;
+        }
         // Scripts / settings: which wake words an ESPHome satellite offers and which are listening.
         // message = { device? } — omitted means every connected one.
         if (obj.command === 'getWakeWords') {
@@ -1966,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') {
@@ -2172,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) {
@@ -2222,29 +2545,93 @@ class Assistant extends adapter_core_1.Adapter {
      * later turns have the full thread.
      */
     answer(question, source = '', origin = {}) {
-        return this.journal
-            ? this.journal.run(question, source, origin, () => this.answerTracked(question, source))
-            : this.answerTracked(question, source);
+        return this.requestOrigin.run({ source, room: origin.room || '' }, () => this.journal
+            ? 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
@@ -2321,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.';
         }
@@ -2332,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 '';
             }
         }
@@ -2342,11 +2735,38 @@ 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
+            // answer with its power state.
+            const yt = this.youtubePlayers.length ? (0, youtube_1.parseYouTubeCommand)(question, this.youtubePlayers) : null;
+            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) {
@@ -2356,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).
@@ -2394,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();
@@ -2405,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() {
@@ -2521,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"). */
@@ -2647,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;
@@ -2680,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) {
@@ -2716,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':
@@ -2758,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');
@@ -2811,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);
@@ -3450,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.');
@@ -3938,6 +4623,383 @@ class Assistant extends adapter_core_1.Adapter {
             },
         };
     }
+    // ── YouTube on the TV (youtube-remote players) ──────────────────────────
+    /** The player a request means: the named one, else the one in the requesting room, else the first. */
+    youtubePlayerFor(name) {
+        return (0, youtube_1.findPlayer)(this.youtubePlayers, name, this.requestOrigin.getStore()?.room || '');
+    }
+    /**
+     * Find the device of a row that names a youtube-remote instance. Done again before every command: the
+     * device id comes from the TV's screen id, so pairing the TV again replaces the device while we run.
+     * false = nothing is paired with that instance.
+     */
+    async resolveYouTubePlayer(player) {
+        if (!player.instance) {
+            return true;
+        }
+        let devices = [];
+        try {
+            const objs = await this.getForeignObjectsAsync(`${player.instance}.*`, 'device');
+            devices = Object.values(objs).map(o => ({ id: o._id, name: this.youtubeDeviceName(o) }));
+        }
+        catch (e) {
+            this.log.debug(`YouTube: cannot read the devices of ${player.instance}: ${e.message}`);
+        }
+        const device = (0, youtube_1.pickDevice)(devices, player);
+        player.base = device?.id || '';
+        player.target = device ? `${device.id}.youtube` : '';
+        if (device && !player.name) {
+            player.name = device.name || player.instance;
+        }
+        return !!device;
+    }
+    /** Display name of an object, in the voice language if it is translated. */
+    youtubeDeviceName(obj) {
+        const name = obj.common?.name;
+        if (typeof name === 'string') {
+            return name;
+        }
+        const lang = String(this.config.voiceLanguage || this.language || 'en');
+        return name?.[lang] || name?.en || obj._id.split('.').pop() || obj._id;
+    }
+    /**
+     * Options of the "Player" column: every youtube-remote instance (it finds its TV itself), and for an
+     * instance with several paired TVs also each of them, to pin a row to one.
+     */
+    async getYouTubeInstances() {
+        const options = [];
+        let instances = [];
+        try {
+            const view = await this.getObjectViewAsync('system', 'instance', {
+                startkey: 'system.adapter.youtube-remote.',
+                endkey: 'system.adapter.youtube-remote.香',
+            });
+            instances = (view?.rows || []).map(r => r.id.replace(/^system\.adapter\./, '')).sort();
+        }
+        catch (e) {
+            this.log.warn(`getYouTubeInstances failed: ${e.message}`);
+        }
+        for (const instance of instances) {
+            const objs = await this.getForeignObjectsAsync(`${instance}.*`, 'device').catch(() => ({}));
+            const devices = Object.values(objs)
+                .map(o => ({ id: o._id, name: this.youtubeDeviceName(o) }))
+                .sort((a, b) => a.id.localeCompare(b.id));
+            const names = devices.map(d => d.name).join(', ');
+            options.push({ label: names ? `${instance} (${names})` : `${instance} (no TV paired)`, value: instance });
+            if (devices.length > 1) {
+                for (const d of devices) {
+                    options.push({ label: `${instance} › ${d.name}`, value: d.id });
+                }
+            }
+        }
+        return options;
+    }
+    /**
+     * Find `query` on YouTube and play it on a player, switching its TV on first. The search runs before
+     * anything is switched: a TV woken for a channel that does not exist would be the worst outcome.
+     *
+     * A TV that has to boot takes 10–30 s, so in that case the reply comes right away and the rest runs
+     * in the background ({@link playWhenTvIsOn}) — over voice, half a minute of silence reads as "did not
+     * hear me". An already running TV is answered only after the player acknowledged the command.
+     */
+    async playYouTube(query, kind, playerName) {
+        const lang = String(this.config.voiceLanguage || this.language || 'en');
+        const player = this.youtubePlayerFor(playerName);
+        if (!player) {
+            const names = this.youtubePlayers.map(p => p.name).join(', ');
+            return { ok: false, text: (0, youtube_1.youtubeReply)(lang, 'unknownPlayer', { query: playerName, names }) };
+        }
+        if (!(await this.resolveYouTubePlayer(player))) {
+            return {
+                ok: false,
+                player: player.name,
+                text: (0, youtube_1.youtubeReply)(lang, 'noDevice', { instance: player.instance }),
+            };
+        }
+        if (!this.config.allowWriteStates) {
+            return { ok: false, player: player.name, text: (0, youtube_1.youtubeReply)(lang, 'noControl') };
+        }
+        let hit = null;
+        let alternatives = [];
+        // Unsaid kind: what is named like a channel is the channel ("spiele Sailing OceanAir auf YouTube"),
+        // anything else a video search — a video search for a channel name finds some video about it.
+        const searchKind = kind === 'auto' ? 'video' : kind;
+        const direct = (0, youtube_1.directYouTubeTarget)(query, searchKind);
+        if (direct) {
+            hit = { kind: searchKind, id: direct, title: query };
+        }
+        else {
+            try {
+                if (kind === 'auto') {
+                    const channels = await (0, youtube_1.searchYouTube)(query, 'channel', { language: lang });
+                    hit = channels.find(h => (0, youtube_1.isNamedChannel)(h, query)) || null;
+                    alternatives = channels.filter(h => h !== hit).slice(0, 3);
+                }
+                if (!hit) {
+                    const hits = await (0, youtube_1.searchYouTube)(query, searchKind, { language: lang });
+                    hit = (0, youtube_1.pickBest)(hits, query);
+                    alternatives = hits.filter(h => h !== hit).slice(0, 3);
+                }
+            }
+            catch (e) {
+                this.log.warn(`YouTube search for "${query}" failed: ${e.message}`);
+                return { ok: false, player: player.name, text: (0, youtube_1.youtubeReply)(lang, 'searchFailed') };
+            }
+            if (!hit) {
+                return {
+                    ok: false,
+                    player: player.name,
+                    text: (0, youtube_1.youtubeReply)(lang, 'notFound', { kind: searchKind, query }),
+                };
+            }
+        }
+        const title = (0, youtube_1.spokenTitle)(hit);
+        this.log.info(`YouTube: ${kind} "${query}" → ${hit.kind} ${hit.id} (${hit.title}) on ${player.name}.`);
+        const reply = { kind: hit.kind, title, player: player.name };
+        if ((await this.tvPower(player)) === 'off') {
+            try {
+                await this.switchTvOn(player);
+            }
+            catch (e) {
+                this.log.warn(`YouTube: cannot switch ${player.power} on: ${e.message}`);
+            }
+            void this.playWhenTvIsOn(player, hit);
+            return {
+                ok: true,
+                hit,
+                alternatives,
+                player: player.name,
+                poweringOn: true,
+                text: (0, youtube_1.youtubeReply)(lang, 'poweringOn', reply),
+            };
+        }
+        if (await this.sendToYouTubePlayer(player, hit.id)) {
+            return { ok: true, hit, alternatives, player: player.name, text: (0, youtube_1.youtubeReply)(lang, 'playing', reply) };
+        }
+        const instance = player.base.split('.').slice(0, 2).join('.');
+        const alive = (await this.getForeignStateAsync(`system.adapter.${instance}.alive`).catch(() => null))?.val;
+        return {
+            ok: false,
+            hit,
+            player: player.name,
+            text: alive ? (0, youtube_1.youtubeReply)(lang, 'noConfirm', reply) : (0, youtube_1.youtubeReply)(lang, 'adapterDown', { instance }),
+        };
+    }
+    /**
+     * Whether the TV of a player is on. `unknown` when there is nothing to tell it by: no power state, or
+     * one that is a button — pressing a toggle button on a TV that is already on would switch it off.
+     */
+    async tvPower(player) {
+        if (!player.power) {
+            return 'unknown';
+        }
+        const obj = await this.getForeignObjectAsync(player.power).catch(() => null);
+        if (!obj) {
+            this.log.warn(`YouTube player ${player.name}: power state ${player.power} does not exist.`);
+            return 'unknown';
+        }
+        const common = obj.common;
+        if (common.read === false || String(common.role || '').startsWith('button')) {
+            this.log.debug(`YouTube player ${player.name}: ${player.power} is a button, the TV state is unknown.`);
+            return 'unknown';
+        }
+        const state = await this.getForeignStateAsync(player.power).catch(() => null);
+        return (0, youtube_1.isPowerOn)(state?.val) ? 'on' : 'off';
+    }
+    /** Write "on" to the power state, in the type the state has. */
+    async switchTvOn(player) {
+        const obj = await this.getForeignObjectAsync(player.power);
+        const type = obj?.common?.type;
+        const val = type === 'number' ? 1 : type === 'string' ? 'on' : true;
+        await this.setForeignStateAsync(player.power, { val, ack: false });
+        this.journal?.stateAccess('set_state', { id: player.power, value: val });
+        this.log.info(`YouTube: switching ${player.name} on (${player.power} = ${JSON.stringify(val)}).`);
+    }
+    /**
+     * After the TV was switched on: wait until its power state confirms (an `ack` from the TV adapter — our
+     * own write already says `true`), give the TV its boot time, then play. The YouTube app is often not
+     * reachable over the lounge right after boot, so a command that is not acknowledged is sent once more.
+     */
+    async playWhenTvIsOn(player, hit) {
+        try {
+            const until = Date.now() + TV_POWER_TIMEOUT_MS;
+            let on = false;
+            while (!on && Date.now() < until) {
+                await this.delay(1000);
+                const st = await this.getForeignStateAsync(player.power).catch(() => null);
+                on = !!st?.ack && (0, youtube_1.isPowerOn)(st.val);
+            }
+            if (!on) {
+                this.log.warn(`YouTube: ${player.power} did not report "on" within ${TV_POWER_TIMEOUT_MS / 1000} s — trying to play anyway.`);
+            }
+            await this.delay(player.delaySec * 1000);
+            let ok = await this.sendToYouTubePlayer(player, hit.id);
+            if (!ok) {
+                await this.delay(YOUTUBE_RETRY_MS);
+                ok = await this.sendToYouTubePlayer(player, hit.id);
+            }
+            if (ok) {
+                this.log.info(`YouTube: playing ${hit.id} (${hit.title}) on ${player.name}.`);
+            }
+            else {
+                this.log.warn(`YouTube: ${player.name} did not take ${hit.id} after power-on. If the TV needs longer to start, raise its start delay.`);
+            }
+        }
+        catch (e) {
+            this.log.warn(`YouTube: playing on ${player.name} failed: ${e.message}`);
+        }
+    }
+    /**
+     * Hand a video/playlist/channel id to the player and wait for its acknowledgement: youtube-remote acks
+     * `youtube` (back to '') only once the TV took the command, and leaves it unacknowledged on failure.
+     */
+    async sendToYouTubePlayer(player, id) {
+        await this.setForeignStateAsync(player.target, { val: id, ack: false });
+        this.journal?.stateAccess('set_state', { id: player.target, value: id });
+        const until = Date.now() + YOUTUBE_ACK_TIMEOUT_MS;
+        while (Date.now() < until) {
+            await this.delay(250);
+            if ((await this.getForeignStateAsync(player.target).catch(() => null))?.ack) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /** A play result as tool / sendTo data: without the internal objects, with the alternatives as titles. */
+    youtubeResultData(res) {
+        return {
+            ok: res.ok,
+            text: res.text,
+            ...(res.player ? { player: res.player } : {}),
+            ...(res.hit ? { kind: res.hit.kind, id: res.hit.id, title: res.hit.title } : {}),
+            ...(res.hit?.channel ? { channel: res.hit.channel } : {}),
+            ...(res.poweringOn ? { poweringOn: true } : {}),
+            ...(res.alternatives?.length
+                ? { otherResults: res.alternatives.map(h => ({ id: h.id, title: h.title })) }
+                : {}),
+        };
+    }
+    /**
+     * LLM tools for the YouTube players: `play_youtube` (search + power-on + play) and `youtube_player`
+     * (pause, skip, volume, what is playing). The configured names go into the descriptions, the model
+     * cannot discover them otherwise.
+     */
+    buildYouTubeTools() {
+        const names = this.youtubePlayers.map((p, i) => (i === 0 ? `${p.name} (default)` : p.name)).join(', ');
+        const playerParam = {
+            type: 'string',
+            description: `Player name or room: ${names}. Leave it out for the player in the room the user is in, else the default.`,
+        };
+        const play = {
+            name: 'play_youtube',
+            description: 'Play something from YouTube on the TV: finds the channel, video or playlist by name, switches ' +
+                'the TV on if it is off and starts playing. Use this for every "play … on YouTube", ' +
+                '"spiele den Kanal …", "zeig das Video …" — never write the player states yourself. kind ' +
+                '"channel" plays the newest uploads of a channel. The reply text of the result can be said as is; ' +
+                'otherResults are the next search hits, offer them if the user says it was the wrong one ' +
+                '(pass the id as query to play one).',
+            parameters: {
+                type: 'object',
+                properties: {
+                    query: {
+                        type: 'string',
+                        description: 'Name of the channel, title of the video/playlist, a search phrase, or an id/URL',
+                    },
+                    kind: {
+                        type: 'string',
+                        enum: ['channel', 'video', 'playlist'],
+                        description: 'Leave it out if the user did not say: a channel of that name wins, else videos',
+                    },
+                    player: playerParam,
+                },
+                required: ['query'],
+                additionalProperties: false,
+            },
+            run: async (args) => {
+                const query = typeof args.query === 'string' ? args.query.trim() : '';
+                if (!query) {
+                    return JSON.stringify({ ok: false, error: 'no query given' });
+                }
+                const kind = args.kind === 'channel' || args.kind === 'playlist' || args.kind === 'video' ? args.kind : 'auto';
+                const player = typeof args.player === 'string' ? args.player : undefined;
+                return JSON.stringify(this.youtubeResultData(await this.playYouTube(query, kind, player)));
+            },
+        };
+        const control = {
+            name: 'youtube_player',
+            description: 'Control a YouTube player or ask what it plays: action play (resume), pause, next, previous, ' +
+                'volume (with "volume" 0-100), mute, unmute, or status (title, channel, play state, TV power).',
+            parameters: {
+                type: 'object',
+                properties: {
+                    action: {
+                        type: 'string',
+                        enum: ['play', 'pause', 'next', 'previous', 'volume', 'mute', 'unmute', 'status'],
+                    },
+                    volume: { type: 'number', description: 'Volume 0-100, only for action volume' },
+                    player: playerParam,
+                },
+                required: ['action'],
+                additionalProperties: false,
+            },
+            run: async (args) => {
+                const player = this.youtubePlayerFor(typeof args.player === 'string' ? args.player : undefined);
+                if (!player) {
+                    return JSON.stringify({ ok: false, error: `unknown player, known are: ${names}` });
+                }
+                if (!(await this.resolveYouTubePlayer(player))) {
+                    return JSON.stringify({ ok: false, error: `no TV is paired with ${player.instance}` });
+                }
+                const action = typeof args.action === 'string' ? args.action : '';
+                if (action === 'status') {
+                    const ids = ['title', 'artist', 'state', 'connected', 'volume'].map(s => `${player.base}.${s}`);
+                    const states = await this.getForeignStatesAsync(`${player.base}.*`).catch(() => ({}));
+                    const val = (i) => states[ids[i]]?.val ?? null;
+                    const power = await this.tvPower(player);
+                    return JSON.stringify({
+                        ok: true,
+                        data: {
+                            player: player.name,
+                            title: val(0),
+                            channel: val(1),
+                            state: { 0: 'paused', 1: 'playing', 2: 'stopped' }[String(val(2))],
+                            connected: val(3),
+                            volume: val(4),
+                            ...(power !== 'unknown' ? { tv: power } : {}),
+                        },
+                    });
+                }
+                if (!this.config.allowWriteStates) {
+                    return JSON.stringify({ ok: false, error: 'device control is disabled in the settings' });
+                }
+                let id;
+                let value;
+                if (action === 'volume') {
+                    const v = Number(args.volume);
+                    if (!Number.isFinite(v)) {
+                        return JSON.stringify({ ok: false, error: 'volume 0-100 needed' });
+                    }
+                    id = `${player.base}.volume`;
+                    value = Math.min(100, Math.max(0, Math.round(v)));
+                }
+                else if (action === 'mute' || action === 'unmute') {
+                    id = `${player.base}.muted`;
+                    value = action === 'mute';
+                }
+                else if (['play', 'pause', 'next', 'previous'].includes(action)) {
+                    id = `${player.base}.${action === 'previous' ? 'prev' : action}`;
+                    value = true;
+                }
+                else {
+                    return JSON.stringify({ ok: false, error: `unknown action '${action}'` });
+                }
+                await this.setForeignStateAsync(id, { val: value, ack: false });
+                this.journal?.stateAccess('set_state', { id, value });
+                return JSON.stringify({ ok: true, data: { player: player.name, [action]: value } });
+            },
+        };
+        return [play, control];
+    }
     // ── Presence: who is at home (roadmap B1) ───────────────────────────────
     /**
      * Build the presence tracker from the configured states, subscribe to them and mirror the result into
@@ -4295,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) },
+                });
             }
         }
     }