iobroker.assistant 1.2.0 → 1.3.0

package/build/main.js

@@ -66,6 +66,9 @@ 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");
+const openrouter_1 = require("./lib/voice/openrouter");
+const piAgent_1 = require("./lib/piAgent");
+const systemAi_1 = require("./lib/systemAi");
 /**
  * How long a rendered weather context line stays valid. Weather adapters refresh every few minutes at best,
  * so re-reading their whole state tree on every single request would be pure overhead.
@@ -89,6 +92,36 @@ 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.
  */
+/** Fields of the Voice tab the voice test takes from the unsaved form (everything an STT or TTS engine is built from). */
+const VOICE_FORM_FIELDS = [
+    'voiceLanguage',
+    'sttProvider',
+    'sttModel',
+    'openrouterSttModel',
+    'voskModel',
+    'ttsProvider',
+    'ttsVoice',
+    'ttsModel',
+    'voiceCredentialType',
+    'voiceApiKey',
+    'voiceCredentialId',
+    'openrouterSpeechKey',
+    'openrouterCredentialId',
+    'openrouterTtsModel',
+    'openrouterVoice',
+    'azureSpeechKey',
+    'azureSpeechRegion',
+    'azureCredentialId',
+    'azureVoice',
+    'awsAccessKeyId',
+    'awsSecretAccessKey',
+    'awsRegion',
+    'awsCredentialId',
+    'awsVoice',
+    'piperVoice',
+];
+/** Of those, the protected ones: the browser never gets them, so an empty value there means "keep the saved one" */
+const VOICE_FORM_SECRETS = ['voiceApiKey', 'openrouterSpeechKey', 'azureSpeechKey', 'awsSecretAccessKey'];
 /** 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;
@@ -197,8 +230,18 @@ function describeIntent(intent) {
     else if (intent.hour !== undefined) {
         text += ` ${intent.hour}:${String(intent.minute ?? 0).padStart(2, '0')}`;
     }
+    if (intent.delaySec !== undefined) {
+        text += ` in ${intent.delaySec} s`;
+    }
+    else if (intent.at) {
+        text += ` at ${intent.at.day ? `+${intent.at.day}d ` : ''}${intent.at.hour}:${String(intent.at.minute).padStart(2, '0')}`;
+    }
     return text;
 }
+/** A device command for later ("in 2 Stunden", "um 22 Uhr") — goes into the calendar, not to the device */
+function isDeferred(intent) {
+    return intent.delaySec !== undefined || !!intent.at;
+}
 const FIXED_REPLIES = {
     de: ['Ok.', 'Erledigt.'],
     en: ['Okay.', 'Done.'],
@@ -228,6 +271,12 @@ function languageLabel(lang) {
 class Assistant extends adapter_core_1.Adapter {
     /** Cloud LLM; `null` with provider "none" (local tiers only) or before `onReady` finished. */
     agent = null;
+    /** Provider "pi-agent": the cloud tier is a pi-agent instance instead of {@link agent}. */
+    piAgent = null;
+    /** The cloud LLM of the instance (own or system-wide settings); `null` without one. */
+    llm = null;
+    /** What of `system.ai` this instance depends on, while it takes the system-wide AI settings. */
+    systemAiWatch = null;
     /** Set once `onReady` initialised the pipeline — with or without a cloud {@link agent}. */
     ready = false;
     mcp = null;
@@ -330,15 +379,30 @@ class Assistant extends adapter_core_1.Adapter {
         // alarms, the local model) answer. The ioBroker tools are still built: the NLU switches through them.
         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));
+        // Provider "pi-agent": the adapter pi-agent is the cloud tier, with its own model, key and tools.
+        const harness = provider === 'pi-agent';
+        // Provider "system" (or no key of its own): provider, model and key of the system-wide AI settings.
+        if (!localOnly && !harness && (0, systemAi_1.usesSystemAi)(cfg)) {
+            await this.watchSystemAi();
+        }
+        const resolved = localOnly || harness ? null : await (0, systemAi_1.resolveLlm)(this, cfg);
+        this.llm = resolved && !('error' in resolved) ? resolved : null;
+        // speech of the same vendor reuses the key of the LLM
+        const llmKey = this.llm ? { provider: this.llm.provider, apiKey: this.llm.apiKey } : null;
         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.'
-                : 'No API key configured — open the adapter settings and enter your LLM API key.');
+        if (harness && !(cfg.piAgentInstance || '').trim()) {
+            this.log.warn('Provider "pi-agent" without an instance — choose the pi-agent instance in the adapter settings.');
+            await this.setStateAsync('info.connection', { val: false, ack: true });
+            return;
+        }
+        if (resolved && 'error' in resolved) {
+            this.log.warn(resolved.error);
             await this.setStateAsync('info.connection', { val: false, ack: true });
             return;
         }
+        if (this.llm?.system) {
+            this.log.info(`LLM from the system-wide AI settings: ${this.llm.provider} · ${this.llm.model || 'auto'}`);
+        }
         try {
             this.mcp = this.journalMcp(await (0, mcp_server_1.createInProcessMcp)({
                 adapter: this,
@@ -359,6 +423,9 @@ class Assistant extends adapter_core_1.Adapter {
             if ((cfg.weatherInstance || '').trim()) {
                 tools.push(this.buildWeatherTool());
             }
+            if ((cfg.calendarInstance || '').trim()) {
+                tools.push(...this.buildCalendarTools());
+            }
             if (cfg.voiceEnabled) {
                 // Only useful with satellites: without voice there is nothing to speak on.
                 tools.push(this.buildAnnounceTool());
@@ -382,13 +449,15 @@ class Assistant extends adapter_core_1.Adapter {
             // Bust the device/room cache when room/function memberships change (new device shows within TTL anyway).
             this.subscribeForeignObjects('enum.rooms.*');
             this.subscribeForeignObjects('enum.functions.*');
-            if (provider !== 'none') {
-                const prov = (0, llm_1.resolveProvider)(provider, cfg.baseUrl);
+            if (harness) {
+                this.piAgent = new piAgent_1.PiAgentHarness(this, cfg.piAgentInstance.trim(), Math.max(5, Number(cfg.piAgentTimeoutSec) || piAgent_1.PI_AGENT_TIMEOUT_SEC) * 1000);
+            }
+            else if (this.llm) {
                 this.agent = new llm_1.LlmAgent({
-                    provider,
-                    apiKey,
-                    model: cfg.model || prov.defaultModel,
-                    baseUrl: prov.baseUrl,
+                    provider: this.llm.provider,
+                    apiKey: this.llm.apiKey,
+                    model: this.llm.model,
+                    baseUrl: this.llm.baseUrl,
                     systemPrompt: cfg.systemPrompt || '',
                     maxTokens: cfg.maxTokens || 1024,
                     tools: tools.map(t => this.journalTool(t)),
@@ -438,8 +507,10 @@ class Assistant extends adapter_core_1.Adapter {
         await this.setupPresence();
         await this.setupTriggers();
         this.log.info(this.agent
-            ? `Assistant ready (provider=${cfg.provider}, model=${this.agent.model || 'auto'}).`
-            : 'Assistant ready without an LLM provider — answering locally only.');
+            ? `Assistant ready (provider=${this.llm?.provider}, model=${this.agent.model || 'auto'}).`
+            : this.piAgent
+                ? `Assistant ready (cloud tier: ${this.piAgent.instance}).`
+                : 'Assistant ready without an LLM provider — answering locally only.');
         if (cfg.useLocalLlm) {
             void this.ensureLocalLlm(); // background: model load/download must not block onReady
         }
@@ -448,20 +519,20 @@ class Assistant extends adapter_core_1.Adapter {
             // Subscribe regardless of the UDP server so writes are always handled (and logged if unroutable).
             this.subscribeStates('tts.text');
             if (cfg.udpServerEnabled) {
-                await this.startVoiceServer(apiKey);
+                await this.startVoiceServer(llmKey);
             }
         }
         if (cfg.wyomingEnabled) {
-            await this.startWyoming(apiKey);
+            await this.startWyoming(llmKey);
         }
         if (cfg.esphomeEnabled) {
-            await this.startEsphome(apiKey);
+            await this.startEsphome(llmKey);
         }
     }
     /** Start the Wyoming TCP endpoint, bridging to the same STT/answer/TTS pipeline as the UDP server. */
-    async startWyoming(mainApiKey) {
+    async startWyoming(llmKey) {
         const cfg = this.config;
-        const creds = await (0, credentials_1.resolveVoiceCredentials)(this, cfg, mainApiKey);
+        const creds = await (0, credentials_1.resolveVoiceCredentials)(this, cfg, llmKey);
         const ctx = this.voiceContext(cfg, creds);
         const language = cfg.voiceLanguage || this.language || '';
         let stt;
@@ -502,14 +573,14 @@ class Assistant extends adapter_core_1.Adapter {
      * linux-voice-assistant). The adapter is the client here — the devices listen on TCP 6053 — and the
      * spoken reply is handed over as a URL, so the little media server comes up together with them.
      */
-    async startEsphome(mainApiKey) {
+    async startEsphome(llmKey) {
         const cfg = this.config;
         const devices = (cfg.esphomeDevices || []).filter(d => d?.ip?.trim());
         if (!devices.length) {
             this.log.warn('ESPHome satellites are enabled, but no device is configured.');
             return;
         }
-        const creds = await (0, credentials_1.resolveVoiceCredentials)(this, cfg, mainApiKey);
+        const creds = await (0, credentials_1.resolveVoiceCredentials)(this, cfg, llmKey);
         const ctx = this.voiceContext(cfg, creds);
         const language = cfg.voiceLanguage || this.language || '';
         let stt;
@@ -597,6 +668,7 @@ class Assistant extends adapter_core_1.Adapter {
                 azure: (cfg.azureVoice || '').trim(),
                 aws: (cfg.awsVoice || '').trim(),
                 piper: (cfg.piperVoice || '').trim(),
+                openrouter: (cfg.openrouterVoice || '').trim(),
             },
             sttFallback: cfg.sttFallback || '',
             ttsFallback: cfg.ttsFallback || '',
@@ -605,6 +677,9 @@ class Assistant extends adapter_core_1.Adapter {
             voskModel: (cfg.voskModel || '').trim(),
             sttModel: (cfg.sttModel || '').trim(),
             ttsModel: (cfg.ttsModel || '').trim(),
+            openrouterSttModel: (cfg.openrouterSttModel || '').trim(),
+            openrouterTtsModel: (cfg.openrouterTtsModel || '').trim(),
+            decodeAudio: audio => this.decodeAudioBufferToPcm(audio),
         };
     }
     /**
@@ -612,9 +687,9 @@ class Assistant extends adapter_core_1.Adapter {
      * AWS cloud, or Vosk / Piper locally); credentials come from the encrypted config fields or the
      * central credential store (voiceCredentialType).
      */
-    async startVoiceServer(mainApiKey) {
+    async startVoiceServer(llmKey) {
         const cfg = this.config;
-        const creds = await (0, credentials_1.resolveVoiceCredentials)(this, cfg, mainApiKey);
+        const creds = await (0, credentials_1.resolveVoiceCredentials)(this, cfg, llmKey);
         const ctx = this.voiceContext(cfg, creds);
         // Raw language (e.g. 'de' or 'zh-cn') — each engine normalises it (ISO for cloud, model per lang for local).
         const language = cfg.voiceLanguage || this.language || '';
@@ -721,6 +796,7 @@ class Assistant extends adapter_core_1.Adapter {
             azure: cfg.azureVoice,
             aws: cfg.awsVoice,
             piper: cfg.piperVoice,
+            openrouter: cfg.openrouterVoice,
         };
         this.journal?.spoken(source, {
             ...info,
@@ -740,8 +816,7 @@ class Assistant extends adapter_core_1.Adapter {
             return this.speechEngines;
         }
         const cfg = this.config;
-        const mainKey = await (0, credentials_1.resolveApiKey)(this, cfg);
-        const creds = await (0, credentials_1.resolveVoiceCredentials)(this, cfg, mainKey);
+        const creds = await (0, credentials_1.resolveVoiceCredentials)(this, cfg, await this.speechLlmKey());
         const ctx = this.voiceContext(cfg, creds);
         const language = cfg.voiceLanguage || this.language || '';
         try {
@@ -829,8 +904,7 @@ class Assistant extends adapter_core_1.Adapter {
             const cfg = { ...this.config, ...overrides };
             const provider = msg.ttsProvider || cfg.ttsProvider || 'openai';
             const language = msg.language || cfg.voiceLanguage || this.language || '';
-            const mainKey = await (0, credentials_1.resolveApiKey)(this, this.config);
-            const creds = await (0, credentials_1.resolveVoiceCredentials)(this, cfg, mainKey);
+            const creds = await (0, credentials_1.resolveVoiceCredentials)(this, cfg, await this.speechLlmKey());
             return await (0, engines_1.listVoices)(provider, this.voiceContext(cfg, creds), language);
         }
         catch (e) {
@@ -1745,7 +1819,36 @@ class Assistant extends adapter_core_1.Adapter {
         });
     }
     /** Invalidate the cached device/room/function listings when a room/function enum changes. */
-    onObjectChange(id, _obj) {
+    /** Vendor and key of the cloud LLM: speech of the same vendor (OpenAI, OpenRouter) reuses the key. */
+    async speechLlmKey() {
+        const provider = this.config.provider || 'openai';
+        const llm = this.llm ?? (provider === 'none' || provider === 'pi-agent' ? null : await (0, systemAi_1.resolveLlm)(this, this.config));
+        return llm && !('error' in llm) ? { provider: llm.provider, apiKey: llm.apiKey } : null;
+    }
+    /**
+     * Restart when the system-wide AI settings this instance takes change — also when they are still empty, so
+     * setting them up in admin starts the instance. The credential is watched too: a new key needs no new id.
+     */
+    async watchSystemAi() {
+        const native = await (0, systemAi_1.readSystemAi)(this);
+        const credentialId = (0, systemAi_1.systemAiSelection)(native)?.credentialId || '';
+        this.systemAiWatch = { fingerprint: (0, systemAi_1.systemAiFingerprint)(native), credentialId };
+        await this.subscribeForeignObjectsAsync(systemAi_1.SYSTEM_AI_ID);
+        if (credentialId) {
+            await this.subscribeForeignObjectsAsync(credentialId);
+        }
+    }
+    onObjectChange(id, obj) {
+        if (this.systemAiWatch && (id === systemAi_1.SYSTEM_AI_ID || id === this.systemAiWatch.credentialId)) {
+            // A credential has no fingerprint: a change of it is a new key.
+            if (id === systemAi_1.SYSTEM_AI_ID && (0, systemAi_1.systemAiFingerprint)(obj?.native) === this.systemAiWatch.fingerprint) {
+                return;
+            }
+            this.log.info(`The system-wide AI settings changed (${id}) — restarting.`);
+            this.systemAiWatch = null;
+            this.restart();
+            return;
+        }
         if (this.listCache && (id.startsWith('enum.rooms.') || id.startsWith('enum.functions.'))) {
             this.listCache.clear();
             this.log.debug(`list cache cleared (object changed: ${id})`);
@@ -2003,14 +2106,23 @@ class Assistant extends adapter_core_1.Adapter {
             }
             return;
         }
-        // STT model dropdown (Vosk): suggest model names for the selected language.
-        if (obj.command === 'getSttModels') {
+        // STT/TTS model dropdowns (Vosk, OpenRouter): suggest model names for the selected provider.
+        if (obj.command === 'getSttModels' || obj.command === 'getTtsModels') {
             const msg = (obj.message || {});
             const cfg = this.config;
-            const provider = msg.sttProvider || cfg.sttProvider || 'openai';
             const language = msg.language || cfg.voiceLanguage || this.language || '';
+            let models = [];
+            try {
+                models =
+                    obj.command === 'getSttModels'
+                        ? await (0, engines_1.listSttModels)(msg.sttProvider || cfg.sttProvider || 'openai', language)
+                        : await (0, engines_1.listTtsModels)(msg.ttsProvider || cfg.ttsProvider || 'openai');
+            }
+            catch (e) {
+                this.log.warn(`${obj.command} failed: ${e.message}`);
+            }
             if (obj.callback) {
-                this.sendTo(obj.from, obj.command, (0, engines_1.listSttModels)(provider, language), obj.callback);
+                this.sendTo(obj.from, obj.command, models, obj.callback);
             }
             return;
         }
@@ -2385,10 +2497,20 @@ class Assistant extends adapter_core_1.Adapter {
             }
             return;
         }
-        // Chat: synthesize an answer to speech (WAV) via the configured TTS engine.
+        // Chat and the voice test of the settings: synthesize to speech (WAV) via the configured TTS engine,
+        // or via the unsaved settings of the Voice tab (`config`).
         if (obj.command === 'tts') {
-            const { text, language } = (obj.message || {});
-            const result = await this.synthesizeToWav(String(text ?? ''), language);
+            const { text, language, config } = (obj.message || {});
+            const cfg = config ? this.withVoiceForm(config) : this.config;
+            const result = await this.synthesizeToWav(String(text ?? ''), language, cfg);
+            if (obj.callback) {
+                this.sendTo(obj.from, obj.command, result, obj.callback);
+            }
+            return;
+        }
+        // Voice test of the settings: recognize a recording with the (unsaved) speech-to-text settings.
+        if (obj.command === 'stt') {
+            const result = await this.transcribeForTest((obj.message || {}));
             if (obj.callback) {
                 this.sendTo(obj.from, obj.command, result, obj.callback);
             }
@@ -2567,7 +2689,8 @@ class Assistant extends adapter_core_1.Adapter {
             data: {
                 provider,
                 fallback: cfg.sttFallback || undefined,
-                model: (cfg.sttModel || cfg.voskModel || '').trim() || undefined,
+                model: (provider === 'openrouter' ? cfg.openrouterSttModel : cfg.sttModel || cfg.voskModel || '').trim() ||
+                    undefined,
                 language: cfg.voiceLanguage || this.language || '',
                 audioMs: origin.audioMs,
                 wakeWord: origin.wakeWord,
@@ -2595,19 +2718,52 @@ class Assistant extends adapter_core_1.Adapter {
         if (followUp) {
             this.journal?.note({ followUp: true });
         }
-        const result = raw.replace(/\s*\[\[LISTEN\]\]\s*/gi, ' ').trim();
+        let result = raw.replace(/\s*\[\[(?:LISTEN|DONE)\]\]\s*/gi, ' ').trim();
+        // The LLM answers a switch command that worked with [[DONE]] alone (see doneHint): a beep on the satellite
+        // instead of a sentence. Where nothing can beep (chat, Telegram), a short word. With more text, that is said.
+        let toned = false;
+        if (!result && /\[\[DONE\]\]/i.test(raw)) {
+            toned = await this.playConfirmationTone(source);
+            if (!toned) {
+                result = this.doneText();
+            }
+        }
         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 },
+            title: toned
+                ? 'Confirmed with a tone instead of words'
+                : result
+                    ? `Answer: ${result.length} characters${followUp ? ', waits for a reply' : ''}`
+                    : 'No spoken answer',
+            data: { answer: result, raw: raw !== result ? raw : undefined, followUp, tone: toned || undefined },
         });
-        if (useCtx && result) {
-            this.context.add(source, question, result);
+        if (useCtx && (result || toned)) {
+            this.context.add(source, question, result || this.doneText());
         }
         return result;
     }
+    /**
+     * System-prompt instruction for `confirmWithTone`: a switch command that worked is answered with [[DONE]]
+     * alone, which becomes a beep on the satellite. Empty when the option (or voice) is off.
+     */
+    doneHint() {
+        if (!this.config.confirmWithTone || !this.config.voiceEnabled) {
+            return '';
+        }
+        const lang = String(this.config.voiceLanguage || this.language || 'en');
+        if (lang === 'ru') {
+            return 'Если запрос был только командой включить, выключить или установить устройства на значение и всё получилось, ответь только управляющим маркером [[DONE]] (вместо фразы прозвучит короткий сигнал). На вопросы, при ошибках или если нужно что-то сообщить, отвечай как обычно.';
+        }
+        if (lang === 'de') {
+            return 'Wenn die Anfrage nur ein Befehl war, Geräte ein- oder auszuschalten oder auf einen Wert zu stellen, und alles geklappt hat, antworte ausschließlich mit dem Steuer-Marker [[DONE]] (statt eines Satzes ertönt ein kurzer Bestätigungston). Bei Fragen, bei Fehlern oder wenn du etwas mitteilen musst, antworte normal.';
+        }
+        return 'If the request was only a command to switch devices on or off or to set them to a value, and everything worked, answer with the control marker [[DONE]] alone (a short beep plays instead of a sentence). For questions, errors or when you have something to tell, answer normally.';
+    }
+    /** What [[DONE]] says where no beep can be played */
+    doneText() {
+        const lang = String(this.config.voiceLanguage || this.language || 'en');
+        return lang === 'ru' ? 'Готово.' : lang === 'de' ? 'Erledigt.' : 'Done.';
+    }
     /** Per source: whether its last {@link answer} asked the user something (LLM-signalled via [[LISTEN]]). */
     followUps = new Map();
     /**
@@ -2800,8 +2956,9 @@ class Assistant extends adapter_core_1.Adapter {
         // 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.
         const useLocal = !!(this.config.useLocalLlm && this.localLlm);
-        const localFirst = useLocal && (!this.agent || !!this.config.localLlmFirst);
-        if (localFirst && (!history.length || !this.agent)) {
+        const cloud = !!(this.agent || this.piAgent);
+        const localFirst = useLocal && (!cloud || !!this.config.localLlmFirst);
+        if (localFirst && (!history.length || !cloud)) {
             const ans = await this.askLocalLlm(question, weather, source);
             if (ans) {
                 return ans;
@@ -2822,6 +2979,9 @@ class Assistant extends adapter_core_1.Adapter {
         }
         // 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).
+        if (this.piAgent) {
+            return this.askPiAgent(this.piAgent, question, weather, source, useLocal && !localFirst);
+        }
         if (!this.agent) {
             // Provider "none": no tier further down. Say so instead of failing — over voice an error is
             // read out as a technical message.
@@ -2838,7 +2998,8 @@ class Assistant extends adapter_core_1.Adapter {
         const mem = this.buildMemoryContext();
         // Only ask the model to emit the follow-up marker when satellites can actually re-open the mic.
         const followUp = this.config.voiceEnabled ? this.followUpHint() : '';
-        const parts = [this.config.systemPrompt || '', followUp, mem, ctx].filter(Boolean);
+        const done = this.doneHint();
+        const parts = [this.config.systemPrompt || '', followUp, done, mem, ctx].filter(Boolean);
         const sys = parts.length ? parts.join('\n\n') : undefined;
         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 —
@@ -2847,7 +3008,7 @@ class Assistant extends adapter_core_1.Adapter {
         const questionForLlm = [time, weather, question].filter(Boolean).join('\n\n');
         this.journal?.note({
             tier: 'cloud',
-            detail: `${this.config.provider || 'openai'} · ${this.agent.model || 'auto'}`,
+            detail: `${this.llm?.provider || this.config.provider || 'openai'} · ${this.agent.model || 'auto'}`,
         });
         // 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.
@@ -2858,6 +3019,7 @@ class Assistant extends adapter_core_1.Adapter {
             data: {
                 systemPrompt: this.config.systemPrompt || '',
                 followUpHint: followUp || undefined,
+                doneHint: done || undefined,
                 memory: mem || undefined,
                 devices: deviceLines,
                 time,
@@ -2884,6 +3046,39 @@ class Assistant extends adapter_core_1.Adapter {
             throw e;
         }
     }
+    /**
+     * Cloud tier through the adapter pi-agent: one pi-agent conversation per source. The style, the
+     * follow-up marker, the memory and the device list are the instructions of that conversation (pi-agent
+     * re-configures it only when they change); time, weather and presence change every turn and go in front
+     * of the question. The history stays in pi-agent, so nothing of {@link ConversationStore} is sent.
+     */
+    async askPiAgent(harness, question, weather, source, localFallback) {
+        const followUp = this.config.voiceEnabled ? this.followUpHint() : '';
+        // The device list maps names to state ids, so pi-agent can act without searching first. It is the
+        // first to go when the instructions get too long — pi-agent can still search.
+        const { text: instructions, dropped } = (0, piAgent_1.composeInstructions)([this.config.systemPrompt || '', followUp, this.doneHint()], [this.buildMemoryContext(), await this.buildDeviceContext()]);
+        if (dropped) {
+            this.log.debug(`pi-agent: ${dropped} context block(s) left out, the instructions would be too long.`);
+        }
+        const text = [this.buildTimeContext(), weather, this.buildPresenceContext(), question]
+            .filter(Boolean)
+            .join('\n\n');
+        this.log.info(`Cloud tier ${harness.instance} (source='${source}') — asking pi-agent…`);
+        this.journal?.note({ tier: 'cloud', detail: harness.instance });
+        try {
+            return await harness.ask({ text, conversation: source, instructions });
+        }
+        catch (e) {
+            if (localFallback) {
+                this.log.warn(`pi-agent 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.
@@ -2974,10 +3169,11 @@ class Assistant extends adapter_core_1.Adapter {
             const room = d.room ? `${d.room}, ` : '';
             lines.push(`- ${d.name} (${room}${d.type}): ${ids.join(', ')}`);
         }
+        const lang = String(this.config.voiceLanguage || this.language || 'en');
+        lines.push(...this.satelliteVolumeLines(lang));
         if (!lines.length) {
             return '';
         }
-        const lang = String(this.config.voiceLanguage || this.language || 'en');
         const header = lang === 'ru'
             ? 'Известные устройства — «имя (комната, тип): stateId». Используй эти stateId напрямую с set_state/get_states; вызывай list_devices только если нужного устройства здесь нет.'
             : lang === 'de'
@@ -2985,6 +3181,41 @@ class Assistant extends adapter_core_1.Adapter {
                 : 'Known devices — "name (room, type): stateId". Use these stateIds directly with set_state/get_states; only call list_devices if a needed device is missing here.';
         return `${header}\n${lines.join('\n')}`;
     }
+    /**
+     * The playback volume of every voice satellite as a line of the device list. Without it, "Lautstärke auf 50
+     * Prozent" that the rules miss reaches the LLM (or pi-agent) with only the media devices of the room in view, and
+     * the model turns those up instead of the speaker that heard the request. The scales differ per transport.
+     */
+    satelliteVolumeLines(lang) {
+        const label = (satId) => lang === 'ru'
+            ? `Громкость голосового спутника ${satId}`
+            : lang === 'de'
+                ? `Lautstärke des Sprachsatelliten ${satId}`
+                : `Volume of the voice satellite ${satId}`;
+        const lines = [];
+        const seen = new Set();
+        for (const [satId, instance] of this.nativeSatFrom) {
+            seen.add(satId);
+            lines.push(`- ${label(satId)} (${satId}, level.volume 0-100): ${instance}.volume`);
+        }
+        for (const [satId, device] of this.satDeviceById) {
+            if (seen.has(satId)) {
+                continue;
+            }
+            const player = this.esphome?.entities(device).find(e => e.kind === 'mediaPlayer');
+            if (player) {
+                seen.add(satId);
+                const id = `${this.namespace}.satellites.${satId}.controls.${player.objectId}.volume`;
+                lines.push(`- ${label(satId)} (${satId}, level.volume 0-1): ${id}`);
+            }
+        }
+        for (const satId of this.satVolumeEnsured) {
+            if (!seen.has(satId)) {
+                lines.push(`- ${label(satId)} (${satId}, level.volume 0-100): ${this.namespace}.satellites.${satId}.volume`);
+            }
+        }
+        return lines;
+    }
     /**
      * List a port we listen on in the host's used-resources registry (js-controller ≥ 8), so the admin shows it
      * as occupied when someone configures another instance. `common.declareUsedResources` is set because the
@@ -3266,7 +3497,8 @@ class Assistant extends adapter_core_1.Adapter {
         if (this.config.confirmWithTone &&
             answer &&
             !failed &&
-            intents.every(i => CONTROL_ACTIONS.has(i.action)) &&
+            // a command for later says when it will run — a beep would hide that
+            intents.every(i => CONTROL_ACTIONS.has(i.action) && !isDeferred(i)) &&
             (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 } });
@@ -3301,6 +3533,9 @@ class Assistant extends adapter_core_1.Adapter {
                 if (!deviceCount) {
                     return 'no devices known';
                 }
+                if (isDeferred(intent) && !(this.config.calendarInstance || '').trim()) {
+                    return 'a command for later needs a calendar (fullcalendar) instance in the settings';
+                }
                 return ['on', 'off', 'level', 'color'].includes(intent.action) && !this.config.allowWriteStates
                     ? 'writing states is not allowed (allowWriteStates)'
                     : '';
@@ -3325,8 +3560,226 @@ class Assistant extends adapter_core_1.Adapter {
             case 'volumeSet':
                 return this.executeVolumeIntent(intent, source);
             default:
-                return this.executeIntent(intent);
+                return isDeferred(intent) ? this.executeDeferredIntent(intent) : this.executeIntent(intent);
+        }
+    }
+    /**
+     * Send a message to the calendar instance (fullcalendar). Its answer `{error}` becomes an exception.
+     *
+     * @param command `addEvent`, `listEvents`, `deleteEvent`, …
+     * @param message the parameters
+     */
+    async calendarCall(command, message) {
+        const instance = (this.config.calendarInstance || '').trim().replace(/^system\.adapter\./, '');
+        if (!instance) {
+            throw new Error('No calendar instance configured in the assistant settings');
+        }
+        const alive = await this.getForeignStateAsync(`system.adapter.${instance}.alive`);
+        if (!alive?.val) {
+            throw new Error(`The calendar ${instance} is not running`);
+        }
+        const res = (await this.sendToAsync(instance, command, message, { timeout: 10000 }));
+        if (!res) {
+            throw new Error(`The calendar ${instance} did not answer`);
+        }
+        if (res.error) {
+            throw new Error(res.error);
+        }
+        return res;
+    }
+    /**
+     * Whether the per-device ACL forbids writing this state: an explicit entry, else the default of the device
+     * type (locks are read-only). States outside the device list are not restricted (like `set_state`).
+     */
+    async writeForbidden(stateId) {
+        const { devices } = await this.getNluDevices();
+        const device = devices.find(d => Object.values(d.controls).includes(stateId));
+        if (!device) {
+            return false;
+        }
+        const entry = this.config.deviceAcl?.[(0, tools_1.deviceKey)(Object.values(device.controls))];
+        return entry ? entry.write === false : device.type === 'lock';
+    }
+    /** "22:30", "morgen um 22:30", "30.10. um 7:00" — when a planned command runs, for the spoken answer */
+    describeWhen(time, lang) {
+        const pad = (n) => String(n).padStart(2, '0');
+        const clock = `${time.getHours()}:${pad(time.getMinutes())}`;
+        const now = new Date();
+        const days = Math.round((new Date(time.getFullYear(), time.getMonth(), time.getDate()).getTime() -
+            new Date(now.getFullYear(), now.getMonth(), now.getDate()).getTime()) /
+            86_400_000);
+        const date = `${pad(time.getDate())}.${pad(time.getMonth() + 1)}.`;
+        if (lang === 'ru') {
+            return days === 0 ? `в ${clock}` : days === 1 ? `завтра в ${clock}` : `${date} в ${clock}`;
+        }
+        if (lang === 'de') {
+            return days === 0 ? `um ${clock}` : days === 1 ? `morgen um ${clock}` : `am ${date} um ${clock}`;
         }
+        return days === 0 ? `at ${clock}` : days === 1 ? `tomorrow at ${clock}` : `on ${date} at ${clock}`;
+    }
+    /**
+     * A device command for later ("Licht in 2 Stunden aus", "выключи свет через 2 часа"): one event in the calendar
+     * (fullcalendar) per write — the calendar shows it, survives restarts and can be cancelled there.
+     */
+    async executeDeferredIntent(intent) {
+        const device = intent.device;
+        if (!device || !intent.stateId) {
+            throw new Error('deferred intent without a device');
+        }
+        const lang = String(this.config.voiceLanguage || this.language || 'en');
+        const pick = (rus, ger, eng) => lang === 'ru' ? rus : lang === 'de' ? ger : eng;
+        const room = intent.room || device.room;
+        const where = room ? ` (${room})` : '';
+        const dev = device.name;
+        if (await this.writeForbidden(intent.stateId)) {
+            return pick(`${dev}${where} только для чтения.`, `${dev}${where} ist schreibgeschützt.`, `${dev}${where} is read-only.`);
+        }
+        let time;
+        if (intent.delaySec !== undefined) {
+            time = new Date(Date.now() + intent.delaySec * 1000);
+        }
+        else {
+            const { hour, minute, day } = intent.at;
+            const now = new Date();
+            time = new Date(now.getFullYear(), now.getMonth(), now.getDate() + (day ?? 0), hour, minute, 0, 0);
+            if (time.getTime() <= now.getTime()) {
+                if (day !== undefined) {
+                    return pick(`${this.describeWhen(time, lang)} уже прошло.`, `${this.describeWhen(time, lang).replace(/^um /, '')} ist schon vorbei.`, `${this.describeWhen(time, lang).replace(/^at /, '')} has already passed.`);
+                }
+                time.setDate(time.getDate() + 1); // "um 7 Uhr" after 7 o'clock: tomorrow
+            }
+        }
+        const name = `${dev}${where}`;
+        await this.calendarCall('addEvent', { oid: intent.stateId, value: intent.value, start: time.getTime(), name });
+        // a dimmer with its own switch: the switch goes into the calendar, too
+        if (intent.also) {
+            await this.calendarCall('addEvent', {
+                oid: intent.also.stateId,
+                value: intent.also.value,
+                start: time.getTime(),
+                name,
+            });
+        }
+        this.log.info(`Planned in the calendar: ${intent.stateId} = ${JSON.stringify(intent.value)} at ${time.toString()}`);
+        const when = this.describeWhen(time, lang);
+        switch (intent.action) {
+            case 'on':
+                return pick(`Хорошо, ${when} включу: ${dev}${where}.`, `Okay, ${dev}${where} wird ${when} eingeschaltet.`, `Okay, ${dev}${where} will be turned on ${when}.`);
+            case 'off':
+                return pick(`Хорошо, ${when} выключу: ${dev}${where}.`, `Okay, ${dev}${where} wird ${when} ausgeschaltet.`, `Okay, ${dev}${where} will be turned off ${when}.`);
+            case 'level':
+                return pick(`Хорошо, ${when} поставлю ${dev}${where} на ${String(intent.value)} %.`, `Okay, ${dev}${where} wird ${when} auf ${String(intent.value)} % gestellt.`, `Okay, ${dev}${where} will be set to ${String(intent.value)} % ${when}.`);
+            default:
+                return pick(`Хорошо, запланировано ${when}: ${dev}${where}.`, `Okay, für ${dev}${where} ${when} eingeplant.`, `Okay, planned for ${dev}${where} ${when}.`);
+        }
+    }
+    /**
+     * LLM tools for the calendar (fullcalendar): plan a state change for later, list what is planned, cancel it.
+     * Planning respects the same write rules as `set_state` (the coarse switch and the per-device ACL).
+     */
+    buildCalendarTools() {
+        const fail = (e) => JSON.stringify({ ok: false, error: e.message });
+        const tools = [
+            {
+                name: 'list_scheduled',
+                description: 'List the planned events of the calendar (state changes at a time, also recurring ones), in local time of the house. Optional "days" ahead (default 1 = the next 24 hours) or a "from"/"to" range as local time "YYYY-MM-DDTHH:mm".',
+                parameters: {
+                    type: 'object',
+                    properties: {
+                        days: { type: 'number', description: 'How many days ahead, default 1' },
+                        from: { type: 'string', description: 'Start, local time YYYY-MM-DDTHH:mm' },
+                        to: { type: 'string', description: 'End, local time YYYY-MM-DDTHH:mm' },
+                    },
+                    additionalProperties: false,
+                },
+                run: async (args) => {
+                    try {
+                        const res = await this.calendarCall('listEvents', {
+                            days: typeof args.days === 'number' ? args.days : 1,
+                            from: args.from,
+                            to: args.to,
+                            max: 50,
+                        });
+                        return JSON.stringify({ ok: true, events: res.events });
+                    }
+                    catch (e) {
+                        return fail(e);
+                    }
+                },
+            },
+        ];
+        if (!this.config.allowWriteStates) {
+            return tools;
+        }
+        tools.push({
+            name: 'schedule_state',
+            description: 'Plan a state change for later in the calendar: write "value" to state "id" after "in_minutes" or at "at" (local time of the house, "YYYY-MM-DDTHH:mm"). Use it for "in 2 hours", "at 10 pm", "tomorrow morning" — never set_state for something meant for later. With "duration_minutes" the state gets "end_value" after that time (for a boolean the opposite by default). Tell the user the planned time.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    id: { type: 'string', description: 'State ID' },
+                    value: { type: ['boolean', 'number', 'string'], description: 'Value to write' },
+                    in_minutes: { type: 'number', description: 'Delay in minutes from now' },
+                    at: { type: 'string', description: 'Local time YYYY-MM-DDTHH:mm' },
+                    duration_minutes: { type: 'number', description: 'Optional: write end_value this much later' },
+                    end_value: { type: ['boolean', 'number', 'string'], description: 'Value after the duration' },
+                    name: {
+                        type: 'string',
+                        description: 'Short title for the calendar, e.g. "Licht Wohnzimmer aus"',
+                    },
+                },
+                required: ['id', 'value'],
+                additionalProperties: false,
+            },
+            run: async (args) => {
+                try {
+                    const id = typeof args.id === 'string' ? args.id : '';
+                    if (await this.writeForbidden(id)) {
+                        return JSON.stringify({
+                            ok: false,
+                            error: `Writing "${id}" is not allowed: the device is read-only in the assistant settings.`,
+                        });
+                    }
+                    if (args.in_minutes === undefined && !args.at) {
+                        return JSON.stringify({ ok: false, error: 'Give "in_minutes" or "at"' });
+                    }
+                    const res = await this.calendarCall('addEvent', {
+                        oid: id,
+                        value: args.value,
+                        in: typeof args.in_minutes === 'number' ? Math.round(args.in_minutes * 60) : undefined,
+                        start: args.in_minutes === undefined ? args.at : undefined,
+                        duration: typeof args.duration_minutes === 'number'
+                            ? Math.round(args.duration_minutes * 60)
+                            : undefined,
+                        endValue: args.end_value,
+                        name: typeof args.name === 'string' ? args.name : undefined,
+                    });
+                    return JSON.stringify({ ok: true, eventId: res.id, start: res.start });
+                }
+                catch (e) {
+                    return fail(e);
+                }
+            },
+        }, {
+            name: 'cancel_scheduled',
+            description: 'Delete a planned event from the calendar, by its "id" from list_scheduled or schedule_state.',
+            parameters: {
+                type: 'object',
+                properties: { id: { type: 'string', description: 'Event ID' } },
+                required: ['id'],
+                additionalProperties: false,
+            },
+            run: async (args) => {
+                try {
+                    await this.calendarCall('deleteEvent', { id: typeof args.id === 'string' ? args.id : '' });
+                    return JSON.stringify({ ok: true });
+                }
+                catch (e) {
+                    return fail(e);
+                }
+            },
+        });
+        return tools;
     }
     /**
      * Speak the weather straight from the configured adapter. Throws when the report has nothing for the
@@ -5916,13 +6369,52 @@ class Assistant extends adapter_core_1.Adapter {
             return { ok: false, error: e.message };
         }
     }
-    /** Build the configured TTS engine (throws when no voice key is available). */
-    async buildTtsEngine() {
-        const cfg = this.config;
-        const mainApiKey = (await (0, credentials_1.resolveApiKey)(this, cfg)) || '';
-        const creds = await (0, credentials_1.resolveVoiceCredentials)(this, cfg, mainApiKey);
+    /**
+     * The saved configuration with the speech settings of an unsaved form on top. Only the speech fields count,
+     * and a key only when one was typed: protected fields never reach the browser, so they are empty there.
+     * Without fallbacks: a test must show whether the chosen engine works, not whether the reserve does.
+     */
+    withVoiceForm(form) {
+        const cfg = { ...this.config, sttFallback: '', ttsFallback: '' };
+        for (const key of VOICE_FORM_FIELDS) {
+            const value = form[key];
+            if (typeof value !== 'string' || (VOICE_FORM_SECRETS.includes(key) && !value.trim())) {
+                continue;
+            }
+            cfg[key] = value;
+        }
+        return cfg;
+    }
+    /** Build the TTS engine of a configuration (throws when no voice key is available). */
+    async buildTtsEngine(cfg = this.config) {
+        const creds = await (0, credentials_1.resolveVoiceCredentials)(this, cfg, await this.speechLlmKey());
         return (0, engines_1.createTtsEngine)(cfg.ttsProvider || 'openai', this.voiceContext(cfg, creds));
     }
+    /**
+     * Speech recognition for the voice test of the settings: a recording of the browser, an uploaded file or the
+     * test sentence the TTS just spoke. WAV is read directly, anything else goes through ffmpeg.
+     */
+    async transcribeForTest(msg) {
+        try {
+            if (!msg.audio) {
+                return { error: 'no audio' };
+            }
+            const cfg = msg.config ? this.withVoiceForm(msg.config) : this.config;
+            const data = Buffer.from(msg.audio, 'base64');
+            const { pcm, sampleRate } = (msg.format || 'wav') === 'wav' && data.toString('latin1', 0, 4) === 'RIFF'
+                ? (0, openrouter_1.pcmFromResponse)(data, '')
+                : await this.decodeAudioBufferToPcm(data);
+            const creds = await (0, credentials_1.resolveVoiceCredentials)(this, cfg, await this.speechLlmKey());
+            const stt = (0, engines_1.createSttEngine)(cfg.sttProvider || 'openai', this.voiceContext(cfg, creds));
+            const language = msg.language || cfg.voiceLanguage || this.language || '';
+            const start = Date.now();
+            const text = await stt.transcribe(pcm, sampleRate, language, await this.buildSttHints());
+            return { text, ms: Date.now() - start, audioMs: Math.round((pcm.length / 2 / sampleRate) * 1000) };
+        }
+        catch (e) {
+            return { error: e.message };
+        }
+    }
     /** True if backend TTS can run (a voice key is configured) — drives the Chat play button. */
     async isTtsAvailable() {
         try {
@@ -5934,15 +6426,23 @@ class Assistant extends adapter_core_1.Adapter {
         }
     }
     /** Synthesize `text` to a base64 WAV via the configured TTS engine (used by the Chat play button). */
-    async synthesizeToWav(text, language) {
+    async synthesizeToWav(text, language, cfg = this.config) {
         if (!text.trim()) {
             return { error: 'empty text' };
         }
         try {
-            const tts = await this.buildTtsEngine();
-            const lang = language || this.config.voiceLanguage || this.language || '';
+            const tts = await this.buildTtsEngine(cfg);
+            const lang = language || cfg.voiceLanguage || this.language || '';
+            const start = Date.now();
             const { pcm, sampleRate } = await tts.synthesize(text, lang);
-            return { audio: this.pcmToWav(pcm, sampleRate).toString('base64'), mime: 'audio/wav' };
+            return {
+                audio: this.pcmToWav(pcm, sampleRate).toString('base64'),
+                mime: 'audio/wav',
+                sampleRate,
+                // a wrong rate shows up as an implausible length of the spoken text
+                audioMs: Math.round((pcm.length / 2 / sampleRate) * 1000),
+                ms: Date.now() - start,
+            };
         }
         catch (e) {
             return { error: e.message };
@@ -5974,7 +6474,8 @@ class Assistant extends adapter_core_1.Adapter {
     async getModels(msg) {
         const cfg = this.config;
         const provider = msg.provider || cfg.provider || 'openai';
-        if (provider === 'none') {
+        // `system`: the model is chosen in the system settings of admin
+        if (provider === 'none' || provider === 'pi-agent' || provider === 'system') {
             return [];
         }
         const apiKey = (0, llm_1.effectiveApiKey)(provider, await (0, credentials_1.resolveApiKey)(this, cfg, {
@@ -6009,6 +6510,19 @@ class Assistant extends adapter_core_1.Adapter {
         if (provider === 'none') {
             return { error: 'No LLM provider selected.' };
         }
+        if (provider === 'pi-agent') {
+            return { error: 'pi-agent has its own connection test in its instance settings.' };
+        }
+        if (provider === 'system') {
+            const llm = await (0, systemAi_1.resolveSystemLlm)(this, await (0, systemAi_1.readSystemAi)(this), true);
+            if ('error' in llm) {
+                return { error: llm.error };
+            }
+            const res = await new llm_1.LlmAgent({ ...llm, maxTokens: 16, tools: [], log: this.log }).testConnection();
+            return res.ok
+                ? { result: `Connection OK (${llm.provider} · ${llm.model || 'auto'})` }
+                : { error: res.error || 'unknown error' };
+        }
         const apiKey = (0, llm_1.effectiveApiKey)(provider, await (0, credentials_1.resolveApiKey)(this, cfg, {
             credentialType: msg.credentialType,
             apiKey: msg.apiKey,