iobroker.assistant 1.0.2 → 1.1.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");
@@ -46,6 +47,7 @@ const timers_1 = require("./lib/timers");
 const alarms_1 = require("./lib/alarms");
 const memory_1 = require("./lib/memory");
 const weather_1 = require("./lib/weather");
+const journal_1 = require("./lib/journal");
 const localLlm_1 = require("./lib/localLlm");
 const credentials_1 = require("./lib/credentials");
 const context_1 = require("./lib/context");
@@ -53,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");
@@ -74,6 +77,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
@@ -187,6 +196,8 @@ class Assistant extends adapter_core_1.Adapter {
     /** Set once `onReady` initialised the pipeline — with or without a cloud {@link agent}. */
     ready = false;
     mcp = null;
+    /** Who asked what and how it was answered (admin chat); null until `onReady` read the config. */
+    journal = null;
     /** Short-TTL cache for the expensive device/room/function listings; invalidated on enum changes. */
     listCache = null;
     /** Cache of a `<base>.SET` level state id → its writable boolean sibling switch (`<base>.ON_SET`/`.ON`), or ''. */
@@ -245,6 +256,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`). */
@@ -270,6 +288,7 @@ class Assistant extends adapter_core_1.Adapter {
         const provider = cfg.provider || 'openai';
         const localOnly = provider === 'none';
         const apiKey = localOnly ? '' : (0, llm_1.effectiveApiKey)(cfg.provider, await (0, credentials_1.resolveApiKey)(this, cfg));
+        await this.setupJournal();
         if (!localOnly && !apiKey) {
             this.log.warn(cfg.credentialType === 'manager'
                 ? 'No credential selected (manager mode) — pick an API-key credential in the adapter settings.'
@@ -278,12 +297,12 @@ class Assistant extends adapter_core_1.Adapter {
             return;
         }
         try {
-            this.mcp = await (0, mcp_server_1.createInProcessMcp)({
+            this.mcp = this.journalMcp(await (0, mcp_server_1.createInProcessMcp)({
                 adapter: this,
                 language: this.language,
                 allowSetState: cfg.allowWriteStates,
                 allowObjectChange: cfg.allowObjectChange,
-            });
+            }));
             this.listCache = new tools_1.ListCache();
             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).
@@ -298,6 +317,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(', ')}`);
@@ -314,7 +345,7 @@ class Assistant extends adapter_core_1.Adapter {
                     baseUrl: prov.baseUrl,
                     systemPrompt: cfg.systemPrompt || '',
                     maxTokens: cfg.maxTokens || 1024,
-                    tools,
+                    tools: tools.map(t => this.journalTool(t)),
                     log: this.log,
                 });
             }
@@ -403,7 +434,7 @@ class Assistant extends adapter_core_1.Adapter {
                 language,
                 stt,
                 tts,
-                answer: question => this.answer(question, 'wyoming'),
+                answer: (question, sttMs) => this.answer(question, 'wyoming', { transport: 'wyoming', sttMs }),
                 getHints: () => this.buildSttHints(),
                 log: this.log,
             });
@@ -463,7 +494,12 @@ class Assistant extends adapter_core_1.Adapter {
             language,
             stt,
             tts,
-            answer: (question, origin) => this.answerVoice(question, origin.device),
+            answer: (question, origin) => this.answerVoice(question, origin.device, {
+                transport: 'esphome',
+                room: origin.room,
+                wakeWord: origin.wakeWord,
+                sttMs: origin.sttMs,
+            }),
             getHints: () => this.buildSttHints(),
             media: this.media,
             mediaHost: (cfg.esphomeMediaHost || '').trim(),
@@ -536,7 +572,7 @@ class Assistant extends adapter_core_1.Adapter {
                 language,
                 stt,
                 tts,
-                answer: (question, ctx) => this.answerVoice(question, ctx.device),
+                answer: (question, ctx) => this.answerVoice(question, ctx.device, { transport: 'udp', room: ctx.room, sttMs: ctx.sttMs }),
                 getHints: () => this.buildSttHints(),
                 log: this.log,
                 onStatus: (device, room, state) => {
@@ -586,11 +622,11 @@ class Assistant extends adapter_core_1.Adapter {
      * not re-trigger onStateChange). The state writes must not block the spoken reply, so they are
      * fire-and-forget.
      */
-    async answerVoice(question, source) {
+    async answerVoice(question, source, origin = {}) {
         this.setStateAsync('text.request', { val: question, ack: true }).catch(() => { });
         this.setQuerySource(source);
         this.log.info(`Voice Q (${source}): ${question}`);
-        const answer = await this.answer(question, source);
+        const answer = await this.answer(question, source, { satellite: source, ...origin });
         this.log.info(`Voice A (${source}): ${answer}`);
         this.setStateAsync('text.response', { val: answer, ack: true }).catch(() => { });
         return answer;
@@ -659,11 +695,17 @@ class Assistant extends adapter_core_1.Adapter {
                 pcm = pcm.subarray(44);
             }
             const language = msg.language || engines.language;
+            const sttStart = Date.now();
             const text = (await engines.stt.transcribe(pcm, rate, language, await this.buildSttHints())).trim();
             if (!text) {
                 return { text: '', answer: '' };
             }
-            const answer = await this.answerVoice(text, source);
+            const answer = await this.answerVoice(text, source, {
+                transport: 'native',
+                room,
+                wakeWord: typeof msg.wakeWord === 'string' ? msg.wakeWord : undefined,
+                sttMs: Date.now() - sttStart,
+            });
             if (!answer) {
                 return { text, answer: '' };
             }
@@ -1914,6 +1956,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') {
@@ -2146,6 +2209,24 @@ class Assistant extends adapter_core_1.Adapter {
             }
             return;
         }
+        // Admin chat: the journal of the last hours (message = { since?: ms }), and wiping it.
+        if (obj.command === 'getJournal') {
+            const since = Number(obj.message?.since) || 0;
+            const result = this.journal?.enabled
+                ? { enabled: true, entries: this.journal.list(since) }
+                : { enabled: false, entries: [] };
+            if (obj.callback) {
+                this.sendTo(obj.from, obj.command, result, obj.callback);
+            }
+            return;
+        }
+        if (obj.command === 'clearJournal') {
+            this.journal?.clear();
+            if (obj.callback) {
+                this.sendTo(obj.from, obj.command, { ok: true }, obj.callback);
+            }
+            return;
+        }
         if (obj.command !== 'ask') {
             return;
         }
@@ -2168,13 +2249,14 @@ class Assistant extends adapter_core_1.Adapter {
             this.log.info(`A: ${answer}`);
             this.setStateAsync('text.response', { val: answer, ack: true }).catch(() => { });
             if (obj.callback) {
-                this.sendTo(obj.from, obj.command, { answer }, obj.callback);
+                // `journaled`: the admin chat gets this exchange from the journal and must not add it twice.
+                this.sendTo(obj.from, obj.command, { answer, journaled: !!this.journal?.enabled }, obj.callback);
             }
         }
         catch (e) {
             this.log.error(`Assistant error: ${e.message}`);
             if (obj.callback) {
-                this.sendTo(obj.from, obj.command, { error: e.message }, obj.callback);
+                this.sendTo(obj.from, obj.command, { error: e.message, journaled: !!this.journal?.enabled }, obj.callback);
             }
         }
     }
@@ -2187,7 +2269,12 @@ class Assistant extends adapter_core_1.Adapter {
      * is applied to the cloud LLM tier; every completed exchange (whichever tier answered) is recorded so
      * later turns have the full thread.
      */
-    async answer(question, source = '') {
+    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.answerTracked(question, source));
+    }
+    async answerTracked(question, source) {
         const useCtx = this.config.useConversationContext !== false;
         const history = useCtx ? this.context.get(source) : [];
         const raw = await this.produceAnswer(question, history, source);
@@ -2195,6 +2282,9 @@ class Assistant extends adapter_core_1.Adapter {
         // (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) {
+            this.journal?.note({ followUp: true });
+        }
         const result = raw.replace(/\s*\[\[LISTEN\]\]\s*/gi, ' ').trim();
         if (useCtx && result) {
             this.context.add(source, question, result);
@@ -2278,6 +2368,7 @@ class Assistant extends adapter_core_1.Adapter {
         if (this.rings.length && (0, nlu_1.isStopCommand)(question)) {
             const n = this.stopRinging();
             this.log.info(`Ring stopped by voice (${n} session(s)).`);
+            this.journal?.note({ tier: 'stop' });
             const lang = String(this.config.voiceLanguage || this.language || 'en');
             return lang === 'ru' ? 'Хорошо.' : lang === 'de' ? 'Ok.' : 'Okay.';
         }
@@ -2288,6 +2379,7 @@ class Assistant extends adapter_core_1.Adapter {
             const asked = this.pending.question(source);
             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 });
                 return '';
             }
         }
@@ -2297,11 +2389,21 @@ class Assistant extends adapter_core_1.Adapter {
         const routine = (0, routines_1.matchRoutine)(question, this.routines);
         if (routine) {
             this.log.info(`Routine '${routine.name}' triggered (source='${source}').`);
+            this.journal?.note({ tier: 'routine', detail: routine.name });
             await this.runRoutine(routine, source);
             return routine.reply;
         }
         // 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 res = await this.playYouTube(yt.query, yt.kind, yt.player);
+                return res.text;
+            }
             try {
                 const handled = await this.tryLocalNlu(question, source);
                 if (handled !== null) {
@@ -2330,6 +2432,7 @@ class Assistant extends adapter_core_1.Adapter {
                 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.');
@@ -2347,6 +2450,7 @@ class Assistant extends adapter_core_1.Adapter {
             // Provider "none": no tier further down. Say so instead of failing — over voice an error is
             // 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' });
             return this.localOnlyFallback();
         }
         const ctx = await this.buildDeviceContext();
@@ -2359,6 +2463,10 @@ class Assistant extends adapter_core_1.Adapter {
         // 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');
+        this.journal?.note({
+            tier: 'cloud',
+            detail: `${this.config.provider || 'openai'} · ${this.agent.model || 'auto'}`,
+        });
         return this.agent.ask(questionForLlm, sys, history);
     }
     /** Reply when nothing local understood the request and there is no cloud LLM (provider "none"). */
@@ -2431,6 +2539,81 @@ class Assistant extends adapter_core_1.Adapter {
         }
         api.registerUsedResource(type, data).catch(e => this.log.debug(`could not register ${type} ${port}: ${e.message}`));
     }
+    /**
+     * Open the conversation journal (shown in the admin chat). Every new or finished entry is mirrored to
+     * `journal.last` as JSON — the chat subscribes to it, which is what makes the view live.
+     */
+    async setupJournal() {
+        const hours = Math.max(0, Math.min(168, Number(this.config.journalHours ?? 24) || 0));
+        const file = path.join(this.instanceDataDir(), 'journal.json');
+        // Also in io-package `instanceObjects`; created here for instances that predate it.
+        await this.setObjectNotExistsAsync('journal', {
+            type: 'channel',
+            common: { name: 'Conversation journal' },
+            native: {},
+        });
+        await this.setObjectNotExistsAsync('journal.last', {
+            type: 'state',
+            common: {
+                name: 'Latest journal entry (JSON; written when a request starts and when it is answered)',
+                type: 'string',
+                role: 'json',
+                read: true,
+                write: false,
+                def: '',
+            },
+            native: {},
+        });
+        this.journal = new journal_1.Journal({
+            hours,
+            file,
+            log: this.log,
+            onChange: entry => {
+                this.setStateAsync('journal.last', { val: JSON.stringify(entry), ack: true }).catch(() => { });
+            },
+        });
+        if (hours) {
+            await this.journal.load();
+        }
+        else {
+            // Switched off: do not keep what was recorded while it was on.
+            await fs.promises.rm(file, { force: true }).catch(() => { });
+        }
+    }
+    /** Wrap the MCP connection so every state the pipeline reads or writes lands in the journal entry. */
+    journalMcp(mcp) {
+        return {
+            listTools: () => mcp.listTools(),
+            callTool: (name, args) => {
+                this.journal?.stateAccess(name, args);
+                return mcp.callTool(name, args);
+            },
+            close: () => mcp.close(),
+        };
+    }
+    /** Wrap an LLM tool so its calls (arguments, result, duration) land in the journal entry. */
+    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;
+                }
+            },
+        };
+    }
+    /** Short name of the local model for the journal ("qwen2.5-1.5b-instruct-q4_k_m"). */
+    localLlmName() {
+        const url = (this.config.localLlmModelUrl || '').trim() || localLlm_1.DEFAULT_LOCAL_MODEL_URL;
+        return (url.split(/[/\\]/).pop() || url).replace(/\?.*$/, '').replace(/\.gguf$/i, '');
+    }
     /** Writable per-instance data dir via the adapter-core function (with a fallback for old runtimes). */
     instanceDataDir() {
         try {
@@ -2559,6 +2742,7 @@ class Assistant extends adapter_core_1.Adapter {
         if (!intents.length || !intents.every(i => this.canExecuteNlu(i, devices.length))) {
             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) {
@@ -3811,6 +3995,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
@@ -4153,6 +4714,7 @@ class Assistant extends adapter_core_1.Adapter {
             }
             try {
                 await this.setForeignStateAsync(write.id, { val: write.value, ack: false });
+                this.journal?.stateAccess('set_state', { id: write.id, value: write.value });
                 this.log.info(`trigger '${def.id}': ${write.id} = ${JSON.stringify(write.value)}`);
             }
             catch (e) {
@@ -4888,6 +5450,12 @@ class Assistant extends adapter_core_1.Adapter {
         catch {
             // ignore
         }
+        try {
+            await this.journal?.flush();
+        }
+        catch {
+            // ignore
+        }
         try {
             await this.mcp?.close();
         }