smart-home-engine 1.52.1 → 1.53.1

package/src/web/ai-tools.js

@@ -38,6 +38,7 @@ const TOOL_DEFINITIONS = [
                 'Search for MQTT topics currently tracked by the she daemon. ' +
                 'Returns matching topic names and their current values. ' +
                 'Use this to discover real topic names before writing scripts. ' +
+                'For everything about a room (its devices, variables and scripts) call describe_room once instead of several searches. ' +
                 'Homematic related topics (under the topic tree hm/) end with STATE for switching actuators and with LEVEL for dimmers.',
             parameters: {
                 type: 'object',
@@ -47,6 +48,11 @@ const TOOL_DEFINITIONS = [
                         description:
                             'An MQTT filter with wildcards (+ one level, # the rest: "hm/status/+/LEVEL", "zigbee2mqtt/#") or a case-insensitive substring of the topic name ("bad"). Empty string lists all topics.',
                     },
+                    queries: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'Several queries in one call (filters or substrings), each answered as with "query"; use this instead of one call per query.',
+                    },
                     value: {
                         type: 'string',
                         description: 'Optional filter on the current value: a plain value for equality ("true", "on", "0"), or a comparison ("> 0", ">= 20", "!= off").',
@@ -61,7 +67,7 @@ const TOOL_DEFINITIONS = [
                         description: 'Maximum number of topics to return (1-500, default 50). The result says how many matched in total.',
                     },
                 },
-                required: ['query'],
+                required: [],
             },
         },
     },
@@ -69,7 +75,8 @@ const TOOL_DEFINITIONS = [
         type: 'function',
         function: {
             name: 'read_script',
-            description: 'Read the content of a script file from the she scripts directory. ' + 'Use this to review existing scripts before suggesting changes.',
+            description:
+                'Read a script file from the she scripts directory, with a header of what the daemon knows about it: its subscriptions, what it publishes, its schedules and the scripts wired to it. Use this to review a script before suggesting changes.',
             parameters: {
                 type: 'object',
                 properties: {
@@ -77,8 +84,13 @@ const TOOL_DEFINITIONS = [
                         type: 'string',
                         description: 'Script file path relative to the scripts directory, e.g. "lights.js" or "lib/utils.js".',
                     },
+                    paths: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'Several scripts in one call (up to 10), each with its header; use this instead of one call per file.',
+                    },
                 },
-                required: ['path'],
+                required: [],
             },
         },
     },
@@ -142,8 +154,13 @@ const TOOL_DEFINITIONS = [
                         type: 'string',
                         description: 'The exact MQTT topic path, e.g. "home/livingroom/light/state".',
                     },
+                    topics: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'Several topics in one call, or one MQTT filter ("var/status/presence/#", up to 20 resolved); use this instead of one call per topic.',
+                    },
                 },
-                required: ['topic'],
+                required: [],
             },
         },
     },
@@ -227,7 +244,7 @@ const TOOL_DEFINITIONS = [
         function: {
             name: 'get_topic_history',
             description:
-                'The values of an MQTT topic over time from InfluxDB (when she has an Influx integration configured), as a compact time series: change points, downsampled when long. ' +
+                'The values of one or several MQTT topics over time from InfluxDB (when she has an Influx integration configured), as compact time series: change points, downsampled when long. Several topics or an MQTT filter ("radar-x/status/#") in one call share the window and the point cap. ' +
                 'Use it for every "why", "when", "how often", "since when" question about a topic; search_mqtt_topics only knows the current value.',
             parameters: {
                 type: 'object',
@@ -236,11 +253,42 @@ const TOOL_DEFINITIONS = [
                         type: 'string',
                         description: 'The MQTT topic, e.g. "hm/status/Licht Bad/LEVEL" (the measurement is derived from it; a measurement name is accepted too).',
                     },
+                    topics: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description:
+                            'Several topics in one call, or one MQTT filter with + or # ("radar-x/status/#", "zigbee2mqtt/tfk_x/+"); up to 20 topics are resolved from the known topics. Use instead of "topic" for a device or a room.',
+                    },
                     from: { type: 'string', description: 'Start: ISO 8601 or relative ("-2h", "-1d", "-7d"). Default "-24h".' },
                     to: { type: 'string', description: 'End: ISO 8601 or relative. Default now.' },
                     limit: { type: 'integer', description: 'Maximum points to return (1-500, default 200); longer series are reduced to change points, then thinned.' },
                 },
-                required: ['topic'],
+            },
+        },
+    },
+    {
+        type: 'function',
+        function: {
+            name: 'get_timeline',
+            description:
+                'The changes of several MQTT topics merged into one chronological list from InfluxDB (when configured): one line per change with the time, the gap to the previous line, the topic and old → new. ' +
+                'Use it to reconstruct what happened in a room or around an event (a presence script, a heating cycle) instead of fetching the topics one by one and merging in your head.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    topics: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'The topics: a list, or one MQTT filter with + or # ("radar-x/status/#"); up to 20 topics are resolved from the known topics.',
+                    },
+                    from: { type: 'string', description: 'Start: ISO 8601 or relative ("-2h", "-1d"). Default "-24h".' },
+                    to: { type: 'string', description: 'End: ISO 8601 or relative. Default now.' },
+                    limit: {
+                        type: 'integer',
+                        description: 'Maximum lines (1-500, default 200); when there are more changes, the ones closest to a previous change of the same topic are dropped first.',
+                    },
+                },
+                required: ['topics'],
             },
         },
     },
@@ -255,11 +303,15 @@ const TOOL_DEFINITIONS = [
                 type: 'object',
                 properties: {
                     topic: { type: 'string', description: 'The exact MQTT topic.' },
+                    topics: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'Several topics in one call, or one MQTT filter (up to 10 topics resolved); the messages of all of them in one list, newest first.',
+                    },
                     from: { type: 'string', description: 'Start: ISO 8601 or relative ("-2h"). Default "-24h".' },
                     to: { type: 'string', description: 'End: ISO 8601 or relative. Default now.' },
                     limit: { type: 'integer', description: 'Maximum messages (1-500, default 100), the newest within the window.' },
                 },
-                required: ['topic'],
             },
         },
     },
@@ -303,9 +355,34 @@ const TOOL_DEFINITIONS = [
             parameters: {
                 type: 'object',
                 properties: {
+                    names: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'Several device names in one call (each answered as with "name").',
+                    },
                     name: { type: 'string', description: 'Device name as it appears in topics or in the discovery.' },
                     limit: { type: 'integer', description: 'Maximum topics per group (default 40).' },
                 },
+            },
+        },
+    },
+    {
+        type: 'function',
+        function: {
+            name: 'describe_room',
+            description:
+                'Everything about a room in one call: every device whose topics carry the room word (grouped per device with values and change ages), the variables with the word, the scripts that subscribe to or publish any of it, and the discovery devices. ' +
+                'Start here for a question about a room ("why does the light in the workshop …"); then narrow with describe_device, get_timeline or get_topic_history.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    name: {
+                        type: 'string',
+                        description:
+                            'The room word as it appears in topic segments: "hobbyraum", "bad", "kitchen". Matched case-insensitively inside a segment ("radar_hobbyraum", "Licht Hobbyraum").',
+                    },
+                    limit: { type: 'integer', description: 'Maximum topics per device (default 15; the note says how many more there are).' },
+                },
                 required: ['name'],
             },
         },
@@ -377,7 +454,7 @@ const TOOL_DEFINITIONS = [
             name: 'propose_script',
             description:
                 'Propose a new or changed script as a draft: the user sees the diff in the chat and applies it with a click; nothing is written without that. ' +
-                'Read the current file first (read_script) and pass the complete new content. Use this instead of pasting the whole file into the answer.',
+                'Read the current file first (read_script) and pass the complete new content. This is how code is handed over: never paste the file into the answer as well; describe the change in a few lines instead.',
             parameters: {
                 type: 'object',
                 properties: {
@@ -389,6 +466,28 @@ const TOOL_DEFINITIONS = [
             },
         },
     },
+    {
+        type: 'function',
+        function: {
+            name: 'run_analysis',
+            description:
+                'Run a short piece of JavaScript you write, in a sandbox with read-only access to the data, and get its return value back as JSON. ' +
+                'Use it for research that would take many tool calls or arithmetic over long lists: counts per hour, correlations between topics, gaps, durations. ' +
+                'The code is the body of an async function; `return` the result (an object or array, kept small). Every data call must be awaited. Available: `await data.topics(filter)` → [{topic, value, ts, lc}] (filter: an MQTT filter or a substring; ts/lc epoch ms); ' +
+                '`await data.history(topics, from, to)` → {topic: [{time, value}]} from InfluxDB (topics: a list or an MQTT filter); `await data.messages(topics, from, to, limit)` → [{time, topic, payload}] from Elasticsearch, newest first (limit up to 5000); ' +
+                '`await data.log(filter, from, to, level, limit)` → [{ts, level, msg}] from the log files; `await data.script(path)` → the source; `data.from`/`data.to` → the window you passed; `await data.time("-2h")` → epoch ms. ' +
+                'from/to are ISO 8601 or relative ("-6h", "-7d"). No require, no network, no publishing, no she object; console.log lines come back with the result; 10 seconds at most.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    code: { type: 'string', description: 'The JavaScript to run, as the body of an async function; must `return` the result.' },
+                    from: { type: 'string', description: 'Optional window start handed to the code as data.from ("-24h").' },
+                    to: { type: 'string', description: 'Optional window end handed to the code as data.to.' },
+                },
+                required: ['code'],
+            },
+        },
+    },
     {
         type: 'function',
         function: {
@@ -441,11 +540,11 @@ async function runTool(name, args, ctx) {
     try {
         switch (name) {
             case 'search_mqtt_topics':
-                return toolSearchMqttTopics(args, ctx.store);
+                return toolSearchMqttTopicsMulti(args, ctx.store);
             case 'get_mqtt_topic':
-                return toolGetMqttTopic(args, ctx.store);
+                return toolGetMqttTopics(args, ctx.store);
             case 'read_script':
-                return toolReadScript(args, ctx.scriptDir);
+                return toolReadScripts(args, ctx.scriptDir, ctx.introspect);
             case 'get_script_logs':
                 return toolGetScriptLogs(args);
             case 'she_fetch':
@@ -460,6 +559,8 @@ async function runTool(name, args, ctx) {
                 return await toolGetMatterAttribute(args);
             case 'get_topic_history':
                 return await toolGetTopicHistory(args, ctx);
+            case 'get_timeline':
+                return await toolGetTimeline(args, ctx);
             case 'get_topic_messages':
                 return await toolGetTopicMessages(args, ctx);
             case 'list_scripts':
@@ -467,7 +568,9 @@ async function runTool(name, args, ctx) {
             case 'who_publishes':
                 return toolWhoPublishes(args, ctx);
             case 'describe_device':
-                return toolDescribeDevice(args, ctx);
+                return toolDescribeDevices(args, ctx);
+            case 'describe_room':
+                return toolDescribeRoom(args, ctx);
             case 'list_services':
                 return toolListServices(args, ctx);
             case 'get_health':
@@ -476,6 +579,8 @@ async function runTool(name, args, ctx) {
                 return toolListTimers(args, ctx);
             case 'propose_script':
                 return toolProposeScript(args, ctx);
+            case 'run_analysis':
+                return await toolRunAnalysis(args, ctx);
             case 'publish_mqtt':
                 return await toolPublishMqtt(args, ctx);
             case 'remember':
@@ -568,6 +673,17 @@ function ago(ms) {
 // Individual tools
 // ---------------------------------------------------------------------------
 
+/** search_mqtt_topics with "queries" (roadmap I39): one search per query, the results one after another */
+function toolSearchMqttTopicsMulti(args, store) {
+    const { queries, ...rest } = args || {};
+    const list = Array.isArray(queries) ? queries.map((q) => String(q)) : typeof queries === 'string' ? [queries] : null;
+    if (!list || list.length === 0) return toolSearchMqttTopics(rest, store);
+    const cap = 10;
+    const out = list.slice(0, cap).map((q) => `# "${q}"\n${toolSearchMqttTopics({ ...rest, query: q }, store)}`);
+    if (list.length > cap) out.push(`… ${list.length - cap} more queries not run; call again with them.`);
+    return out.join('\n\n');
+}
+
 function toolSearchMqttTopics({ query = '', value, changed_within, offset = 0, limit = 50 }, store) {
     if (!store) return 'MQTT state store not available.';
     const pattern = String(query).trim();
@@ -596,7 +712,18 @@ function toolSearchMqttTopics({ query = '', value, changed_within, offset = 0, l
     return lines.join('\n');
 }
 
-function toolReadScript({ path: relPath }, scriptDir) {
+/** read_script with "paths" (roadmap I39): every file with its header, in one result */
+function toolReadScripts(args, scriptDir, introspect) {
+    const { paths, ...rest } = args || {};
+    const list = Array.isArray(paths) ? paths.map((x) => String(x)) : typeof paths === 'string' ? [paths] : null;
+    if (!list || list.length === 0) return toolReadScript(rest, scriptDir, introspect);
+    const cap = 10;
+    const out = [...new Set(list)].slice(0, cap).map((p) => toolReadScript({ path: p }, scriptDir, introspect));
+    if (list.length > cap) out.push(`… ${list.length - cap} more paths not read; call again with them.`);
+    return out.join('\n\n');
+}
+
+function toolReadScript({ path: relPath }, scriptDir, introspect) {
     if (!scriptDir) return 'Scripts directory not configured.';
     if (!relPath || typeof relPath !== 'string') return 'path argument is required.';
     const abs = path.resolve(scriptDir, relPath.replace(/^\/+/, ''));
@@ -606,7 +733,46 @@ function toolReadScript({ path: relPath }, scriptDir) {
     }
     if (!fs.existsSync(abs)) return `File not found: ${relPath}`;
     const content = fs.readFileSync(abs, 'utf8');
-    return `## ${relPath}\n\`\`\`javascript\n${content}\n\`\`\``;
+    return `## ${relPath}\n${scriptSurroundings(relPath, introspect)}\`\`\`javascript\n${content}\n\`\`\``;
+}
+
+/**
+ * What the daemon knows about a loaded script (roadmap I35), as a short header above its source: its
+ * subscriptions and seen publishes, its schedules and pending timers, and the scripts wired to it — those that
+ * subscribe to what it publishes or publish what it subscribes to. Empty when the daemon's state is not
+ * available or the file is not loaded.
+ */
+function scriptSurroundings(relPath, introspect) {
+    if (!introspect?.scripts) return '';
+    const all = introspect.scripts();
+    const norm = (x) => String(x).replace(/^\/+/, '');
+    const sc = all.find((x) => norm(x.label) === norm(relPath) || (x.file && norm(x.file).endsWith('/' + norm(relPath))));
+    if (!sc) return '';
+    const varPrefix = introspect.config ? introspect.config().variablePrefix || 'var' : 'var';
+    const some = (arr, n = 10) => (arr.length <= n ? arr.join(', ') : arr.slice(0, n).join(', ') + ` … (${arr.length} total)`);
+    const lines = [];
+    const subs = [...sc.subscriptions, ...sc.varSubscriptions.map((k) => `${varPrefix}/status/${k}`)];
+    if (subs.length) lines.push(`subscribes: ${some(subs)}`);
+    if (sc.publishes.length) lines.push(`publishes (seen since start): ${some(sc.publishes)}`);
+    const sched = [...sc.jobs.map((j) => `job ${inTime(j.next)}`), ...sc.sunEvents.map((e) => `${e.pattern} ${inTime(e.next)}`)];
+    if (sched.length) lines.push(`schedules: ${some(sched, 6)}`);
+    if (sc.timers.length) lines.push(`pending timers: ${sc.timers.length}`);
+    // a variable published as <prefix>/set/x is read by others as <prefix>/status/x
+    const asStatus = (t) => String(t).replace(new RegExp(`^${varPrefix}/set/`), `${varPrefix}/status/`);
+    const pubs = new Set(sc.publishes.map(asStatus));
+    const subSet = new Set(subs);
+    const readers = [];
+    const writers = [];
+    for (const o of all) {
+        if (o === sc) continue;
+        const oSubs = [...o.subscriptions, ...o.varSubscriptions.map((k) => `${varPrefix}/status/${k}`)];
+        if (oSubs.some((t) => pubs.has(t))) readers.push(o.label);
+        if (o.publishes.some((t) => subSet.has(asStatus(t)))) writers.push(o.label);
+    }
+    if (readers.length) lines.push(`read by: ${some(readers)} (they subscribe to what this script publishes)`);
+    if (writers.length) lines.push(`fed by: ${some(writers)} (they publish what this script subscribes to)`);
+    if (!lines.length) return '';
+    return lines.map((l) => `- ${l}`).join('\n') + '\n';
 }
 
 const LEVEL_RANK = { debug: 0, info: 1, warn: 2, error: 3 };
@@ -623,15 +789,8 @@ function logFilesOldestFirst() {
     return names.sort((a, b) => rank(b) - rank(a)).map((n) => path.join(LOGS_DIR, n));
 }
 
-async function toolGetScriptLogs({ script_name = '', from, to, level = 'debug', limit = 50, offset = 0 } = {}) {
-    const cap = Math.min(Math.max(1, Number(limit) || 50), 200);
-    const skip = Math.max(0, Number(offset) || 0);
-    const needle = String(script_name).toLowerCase();
-    const minRank = LEVEL_RANK[String(level).toLowerCase()] ?? 0;
-    const now = Date.now();
-    const fromMs = from ? parseTime(from, now) : null;
-    const toMs = parseTime(to, now);
-    if (Number.isNaN(fromMs) || Number.isNaN(toMs)) return `from/to must be ISO 8601 or relative ("-2h"); got from=${from}, to=${to}.`;
+/** every log entry matching the filter, oldest first: the files on disk, the in-memory ring only without them */
+async function collectLogEntries({ needle = '', fromMs = null, toMs = Date.now(), minRank = 0 } = {}) {
     const keep = (e) => (fromMs === null || e.ts >= fromMs) && e.ts <= toMs && (LEVEL_RANK[e.level] ?? 0) >= minRank && (!needle || e.msg.toLowerCase().includes(needle));
 
     // the files on disk; the in-memory ring only when there are none (tests, a read-only data directory)
@@ -660,6 +819,19 @@ async function toolGetScriptLogs({ script_name = '', from, to, level = 'debug',
     if (files.length === 0) {
         for (const e of getLogBuffer()) if (keep(e)) matches.push(e);
     }
+    return matches;
+}
+
+async function toolGetScriptLogs({ script_name = '', from, to, level = 'debug', limit = 50, offset = 0 } = {}) {
+    const cap = Math.min(Math.max(1, Number(limit) || 50), 200);
+    const skip = Math.max(0, Number(offset) || 0);
+    const needle = String(script_name).toLowerCase();
+    const minRank = LEVEL_RANK[String(level).toLowerCase()] ?? 0;
+    const now = Date.now();
+    const fromMs = from ? parseTime(from, now) : null;
+    const toMs = parseTime(to, now);
+    if (Number.isNaN(fromMs) || Number.isNaN(toMs)) return `from/to must be ISO 8601 or relative ("-2h"); got from=${from}, to=${to}.`;
+    const matches = await collectLogEntries({ needle, fromMs, toMs, minRank });
     const end = Math.max(0, matches.length - skip);
     const recent = matches.slice(Math.max(0, end - cap), end);
     if (recent.length === 0) {
@@ -698,24 +870,36 @@ function thinSeries(rows, limit) {
     return { points: thinned, note: `${rows.length} points, ${changes.length} change points, every ${k}th shown` };
 }
 
-async function toolGetTopicHistory({ topic, from = '-24h', to, limit = 200 } = {}) {
-    if (!topic) return 'topic is required.';
-    let influx;
-    try {
-        influx = require('../influx');
-    } catch {
-        return 'InfluxDB is not available.';
+/**
+ * The topics a tool call names (roadmap I32): `topics` (a list, or one MQTT filter resolved against the known
+ * topics), else `topic`; a filter needs the store. Capped; the note says when the cap cut the list.
+ */
+function resolveTopics({ topic, topics }, store, cap = 20) {
+    const raw = [];
+    if (Array.isArray(topics)) raw.push(...topics);
+    else if (typeof topics === 'string' && topics.trim()) raw.push(topics);
+    if (typeof topic === 'string' && topic.trim()) raw.push(topic);
+    const out = [];
+    let note = '';
+    for (const t of raw.map((x) => String(x).trim()).filter(Boolean)) {
+        if (/[+#]/.test(t)) {
+            if (!store) return { topics: [], error: `"${t}" is a filter, but the MQTT state store is not available to resolve it; name the topics.` };
+            const matches = [];
+            for (const [name] of store.mqttEntries()) if (mqttWildcard(name, t)) matches.push(name);
+            if (matches.length === 0) return { topics: [], error: `No known topic matches "${t}".` };
+            matches.sort();
+            if (matches.length > cap) note = `${matches.length} topics match "${t}", the first ${cap} are shown; narrow the filter for the rest.`;
+            out.push(...matches.slice(0, cap));
+        } else out.push(t);
     }
-    const mode = influx.getMode?.();
-    if (!mode) return 'No InfluxDB integration is configured in she (config "influx"), so there is no history. The current value: get_mqtt_topic.';
-    if (mode !== 'v1') return 'Topic history is implemented for InfluxDB 1.x only so far.';
-    const now = Date.now();
-    const fromMs = parseTime(from, now);
-    const toMs = parseTime(to, now);
-    if (Number.isNaN(fromMs) || Number.isNaN(toMs)) return `from/to must be ISO 8601 or relative ("-2h"); got from=${from}, to=${to}.`;
-    const cap = Math.min(Math.max(1, Number(limit) || 200), 500);
+    const unique = [...new Set(out)];
+    if (unique.length > cap) note = note || `${unique.length} topics named, the first ${cap} are shown.`;
+    return { topics: unique.slice(0, cap), note };
+}
+
+/** one topic's rows from Influx 1.x: influx4mqtt's measurements first, then she's own schema */
+async function fetchTopicSeries(influx, topic, fromMs, toMs) {
     const tried = [];
-    // influx4mqtt's measurements first, then she's own schema (measurement "mqtt", tag "topic", field "value")
     const queries = measurementCandidates(topic).map((m) => [
         m,
         `SELECT "value" FROM "${m.replace(/"/g, '\\"')}" WHERE time >= ${fromMs}ms AND time <= ${toMs}ms ORDER BY time ASC LIMIT 5000`,
@@ -726,26 +910,156 @@ async function toolGetTopicHistory({ topic, from = '-24h', to, limit = 200 } = {
     ]);
     for (const [m, q] of queries) {
         tried.push(m);
-        let rows;
-        try {
-            rows = await influx.v1Query(q);
-        } catch (e) {
-            return `InfluxDB query failed: ${e.message}`;
+        const rows = await influx.v1Query(q);
+        if (rows && rows.length > 0) return { measurement: m, rows: rows.map((r) => ({ time: r.time, value: r.value })), tried };
+    }
+    return { measurement: null, rows: [], tried };
+}
+
+function influxForHistory() {
+    let influx;
+    try {
+        influx = require('../influx');
+    } catch {
+        return { error: 'InfluxDB is not available.' };
+    }
+    const mode = influx.getMode?.();
+    if (!mode) return { error: 'No InfluxDB integration is configured in she (config "influx"), so there is no history. The current value: get_mqtt_topic.' };
+    if (mode !== 'v1') return { error: 'Topic history is implemented for InfluxDB 1.x only so far.' };
+    return { influx };
+}
+
+async function toolGetTopicHistory({ topic, topics, from = '-24h', to, limit = 200 } = {}, ctx = {}) {
+    const resolved = resolveTopics({ topic, topics }, ctx.store);
+    if (resolved.error) return resolved.error;
+    if (resolved.topics.length === 0) return 'topic (or topics) is required.';
+    const { influx, error } = influxForHistory();
+    if (error) return error;
+    const now = Date.now();
+    const fromMs = parseTime(from, now);
+    const toMs = parseTime(to, now);
+    if (Number.isNaN(fromMs) || Number.isNaN(toMs)) return `from/to must be ISO 8601 or relative ("-2h"); got from=${from}, to=${to}.`;
+    const cap = Math.min(Math.max(1, Number(limit) || 200), 500);
+    const perTopic = Math.max(10, Math.floor(cap / resolved.topics.length));
+    let results;
+    try {
+        results = await Promise.all(resolved.topics.map((t) => fetchTopicSeries(influx, t, fromMs, toMs)));
+    } catch (e) {
+        return `InfluxDB query failed: ${e.message}`;
+    }
+    const blocks = [];
+    results.forEach((r, i) => {
+        const t = resolved.topics[i];
+        if (r.rows.length === 0) {
+            blocks.push(`No history for ${t} between ${isoShort(fromMs)} and ${isoShort(toMs)} (tried measurements ${r.tried.map((m) => `"${m}"`).join(', ')}).`);
+            return;
         }
-        if (!rows || rows.length === 0) continue;
-        const series = rows.map((r) => ({ time: r.time, value: r.value }));
-        const { points, note } = thinSeries(series, cap);
+        const { points, note } = thinSeries(r.rows, perTopic);
         const lines = [
-            `History of ${topic} (measurement "${m}") from ${isoShort(fromMs)} to ${isoShort(toMs)}${rows.length >= 5000 ? ', the first 5000 points of the window' : ''}${note ? `; ${note}` : ''}:`,
+            `History of ${t} (measurement "${r.measurement}") from ${isoShort(fromMs)} to ${isoShort(toMs)}${r.rows.length >= 5000 ? ', the first 5000 points of the window' : ''}${note ? `; ${note}` : ''}:`,
         ];
         for (const pt of points) lines.push(`${isoShort(pt.time)}  ${JSON.stringify(pt.value)}`);
-        return lines.join('\n');
+        blocks.push(lines.join('\n'));
+    });
+    const head =
+        resolved.topics.length > 1
+            ? [`${resolved.topics.length} topics, up to ${perTopic} points each${resolved.note ? `; ${resolved.note}` : ''}.`]
+            : resolved.note
+              ? [resolved.note]
+              : [];
+    return [...head, ...blocks].join('\n\n');
+}
+
+/** a gap between two changes, short: "+12s", "+5m12s", "+2h05m", "+3d 4h" */
+function gapStr(ms) {
+    const s = Math.round(ms / 1000);
+    if (s < 60) return `+${s}s`;
+    const m = Math.floor(s / 60);
+    if (m < 60) return `+${m}m${String(s % 60).padStart(2, '0')}s`;
+    const h = Math.floor(m / 60);
+    if (h < 48) return `+${h}h${String(m % 60).padStart(2, '0')}m`;
+    return `+${Math.floor(h / 24)}d ${h % 24}h`;
+}
+
+/** the longest common prefix of the topics, cut at a slash */
+function commonTopicPrefix(topics) {
+    if (topics.length < 2) return '';
+    let prefix = topics[0];
+    for (const t of topics.slice(1)) {
+        let i = 0;
+        while (i < prefix.length && i < t.length && prefix[i] === t[i]) i++;
+        prefix = prefix.slice(0, i);
     }
-    return `No history for ${topic} between ${isoShort(fromMs)} and ${isoShort(toMs)} (tried measurements ${tried.map((m) => `"${m}"`).join(', ')}).`;
+    const cut = prefix.lastIndexOf('/');
+    return cut === -1 ? '' : prefix.slice(0, cut + 1);
 }
 
-async function toolGetTopicMessages({ topic, from = '-24h', to, limit = 100 } = {}, ctx = {}) {
-    if (!topic) return 'topic is required.';
+/**
+ * The timeline tool (roadmap I33): the change points of several topics merged and sorted. When there are more
+ * than the cap, the changes closest to the previous change of the same topic go first (a flapping sensor loses
+ * its flaps, a door its single opening never); the first change of every topic always stays.
+ */
+async function toolGetTimeline({ topics, topic, from = '-24h', to, limit = 200 } = {}, ctx = {}) {
+    const resolved = resolveTopics({ topic, topics }, ctx.store);
+    if (resolved.error) return resolved.error;
+    if (resolved.topics.length === 0) return 'topics is required: a list of topics or an MQTT filter.';
+    const { influx, error } = influxForHistory();
+    if (error) return error;
+    const now = Date.now();
+    const fromMs = parseTime(from, now);
+    const toMs = parseTime(to, now);
+    if (Number.isNaN(fromMs) || Number.isNaN(toMs)) return `from/to must be ISO 8601 or relative ("-2h"); got from=${from}, to=${to}.`;
+    const cap = Math.min(Math.max(1, Number(limit) || 200), 500);
+    let results;
+    try {
+        results = await Promise.all(resolved.topics.map((t) => fetchTopicSeries(influx, t, fromMs, toMs)));
+    } catch (e) {
+        return `InfluxDB query failed: ${e.message}`;
+    }
+    const entries = [];
+    const missing = [];
+    results.forEach((r, i) => {
+        const t = resolved.topics[i];
+        if (r.rows.length === 0) {
+            missing.push(t);
+            return;
+        }
+        let prev;
+        let prevTime = null;
+        for (const row of r.rows) {
+            if (prevTime !== null && row.value === prev) continue;
+            entries.push({ time: row.time, topic: t, from: prevTime === null ? undefined : prev, to: row.value, gapSame: prevTime === null ? Infinity : row.time - prevTime });
+            prev = row.value;
+            prevTime = row.time;
+        }
+    });
+    if (entries.length === 0) return `No history for ${resolved.topics.join(', ')} between ${isoShort(fromMs)} and ${isoShort(toMs)}.`;
+    const total = entries.length;
+    let kept = entries;
+    if (entries.length > cap) {
+        // the changes with the largest distance to their topic's previous change stay (the first of each is Infinity)
+        kept = [...entries].sort((a, b) => b.gapSame - a.gapSame).slice(0, cap);
+    }
+    kept.sort((a, b) => a.time - b.time || a.topic.localeCompare(b.topic));
+    const prefix = commonTopicPrefix(resolved.topics);
+    const short = (t) => (prefix && t.startsWith(prefix) ? t.slice(prefix.length) : t);
+    const head = [
+        `Timeline of ${resolved.topics.length} topic(s)${prefix ? ` under ${prefix}` : ''} from ${isoShort(fromMs)} to ${isoShort(toMs)}: ${kept.length}${kept.length < total ? ` of ${total}` : ''} changes${kept.length < total ? ' (the ones closest to a previous change of the same topic dropped)' : ''}${resolved.note ? `; ${resolved.note}` : ''}.`,
+    ];
+    if (missing.length) head.push(`No history for: ${missing.map(short).join(', ')}.`);
+    const lines = kept.map((e, i) => {
+        const gap = i === 0 ? '' : gapStr(e.time - kept[i - 1].time);
+        const change = e.from === undefined ? `${JSON.stringify(e.to)} (first value in the window)` : `${JSON.stringify(e.from)} → ${JSON.stringify(e.to)}`;
+        return `${isoShort(e.time)}  ${gap.padStart(8)}  ${short(e.topic)}: ${change}`;
+    });
+    return [...head, ...lines].join('\n');
+}
+
+async function toolGetTopicMessages({ topic, topics, from = '-24h', to, limit = 100 } = {}, ctx = {}) {
+    const resolved = resolveTopics({ topic, topics }, ctx.store, 10);
+    if (resolved.error) return resolved.error;
+    if (resolved.topics.length === 0) return 'topic (or topics) is required.';
+    const many = resolved.topics.length > 1;
     let client = null;
     try {
         client = require('../elastic').getClient();
@@ -764,21 +1078,24 @@ async function toolGetTopicMessages({ topic, from = '-24h', to, limit = 100 } =
         res = await client.search({
             index,
             size: cap,
-            query: { bool: { filter: [{ term: { topic: String(topic) } }, { range: { '@timestamp': { gte: fromMs, lte: toMs } } }] } },
+            query: {
+                bool: { filter: [many ? { terms: { topic: resolved.topics } } : { term: { topic: resolved.topics[0] } }, { range: { '@timestamp': { gte: fromMs, lte: toMs } } }] },
+            },
             sort: [{ '@timestamp': { order: 'desc' } }],
-            _source: ['@timestamp', 'payload'],
+            _source: many ? ['@timestamp', 'topic', 'payload'] : ['@timestamp', 'payload'],
         });
     } catch (e) {
         return `Elasticsearch query failed: ${e.message}`;
     }
     const hits = res?.hits?.hits ?? res?.body?.hits?.hits ?? [];
     const total = res?.hits?.total?.value ?? res?.body?.hits?.total?.value ?? hits.length;
-    if (hits.length === 0) return `No messages for ${topic} between ${isoShort(fromMs)} and ${isoShort(toMs)} in ${index}.`;
-    const lines = [`${hits.length} of ${total} messages for ${topic} from ${isoShort(fromMs)} to ${isoShort(toMs)}, newest first:`];
+    const label = many ? `${resolved.topics.length} topics (${resolved.topics.join(', ')})` : resolved.topics[0];
+    if (hits.length === 0) return `No messages for ${label} between ${isoShort(fromMs)} and ${isoShort(toMs)} in ${index}.`;
+    const lines = [`${hits.length} of ${total} messages for ${label} from ${isoShort(fromMs)} to ${isoShort(toMs)}, newest first${resolved.note ? `; ${resolved.note}` : ''}:`];
     for (const h of hits) {
         const src = h._source || {};
         const ts = typeof src['@timestamp'] === 'number' ? src['@timestamp'] : Date.parse(src['@timestamp']);
-        lines.push(`${isoShort(ts)}  ${String(src.payload ?? '')}`);
+        lines.push(`${isoShort(ts)}  ${many ? String(src.topic ?? '') + '  ' : ''}${String(src.payload ?? '')}`);
     }
     return lines.join('\n');
 }
@@ -881,6 +1198,210 @@ function toolDescribeDevice({ name, limit = 40 } = {}, ctx = {}) {
     return lines.join('\n');
 }
 
+/** describe_device with "names" (roadmap I34): one sheet per name, in one result */
+function toolDescribeDevices({ name, names, limit } = {}, ctx = {}) {
+    const list = [...(Array.isArray(names) ? names : typeof names === 'string' && names.trim() ? [names] : []), ...(name ? [name] : [])]
+        .map((n) => String(n).trim())
+        .filter(Boolean);
+    const unique = [...new Set(list)];
+    if (unique.length === 0) return 'name (or names) is required.';
+    if (unique.length === 1) return toolDescribeDevice({ name: unique[0], limit }, ctx);
+    const cap = 10;
+    const out = unique.slice(0, cap).map((n) => `# ${n}\n${toolDescribeDevice({ name: n, limit }, ctx)}`);
+    if (unique.length > cap) out.push(`… ${unique.length - cap} more names not shown; call again with them.`);
+    return out.join('\n\n');
+}
+
+/**
+ * The room sheet (roadmap I34): the topics whose segments carry the room word, grouped per device — the device
+ * is the adapter instance plus the segment that carries the word (`zigbee2mqtt/radar_hobbyraum`,
+ * `hm/Licht Hobbyraum`, or the first segment itself when it carries the word, `radar-hobbyraum`) — the
+ * variables, the scripts touching any of it, the discovery devices.
+ */
+function toolDescribeRoom({ name, limit = 15 } = {}, ctx = {}) {
+    if (!name) return 'name is required.';
+    const store = ctx.store;
+    if (!store) return 'MQTT state store not available.';
+    const q = String(name).trim().toLowerCase();
+    if (!q) return 'name is required.';
+    const cap = Math.min(Math.max(1, Number(limit) || 15), 100);
+    const now = Date.now();
+    const varPrefix = ctx.introspect?.config ? ctx.introspect.config().variablePrefix || 'var' : 'var';
+    const devices = new Map(); // key → { topics: [{topic, kind, line}] }
+    const variables = [];
+    const roomTopics = new Set();
+    for (const [topic, obj] of store.mqttEntries()) {
+        const segs = topic.split('/');
+        const hitIdx = segs.findIndex((sg) => sg.toLowerCase().includes(q));
+        if (hitIdx === -1) continue;
+        roomTopics.add(topic);
+        const lc = obj.lc ?? obj.ts;
+        const line = `${topic}: ${JSON.stringify(obj.val)}${lc ? ` (changed ${ago(now - lc)} ago)` : ''}`;
+        if (segs[0] === varPrefix) {
+            variables.push(line);
+            continue;
+        }
+        const kind = segs[1] === 'status' ? 'status' : segs[1] === 'set' ? 'set' : segs[1] === 'maintenance' ? 'maintenance' : 'other';
+        const key = hitIdx === 0 ? segs[0] : `${segs[0]}/${segs[hitIdx]}`;
+        if (!devices.has(key)) devices.set(key, []);
+        devices.get(key).push({ kind, line });
+    }
+    if (devices.size === 0 && variables.length === 0) return `No topic segment contains "${name}". Try search_mqtt_topics with a substring, or another spelling of the room.`;
+    const lines = [`Room "${name}": ${devices.size} device(s), ${variables.length} variable(s), ${roomTopics.size} topic(s).`];
+    const order = { status: 0, set: 1, maintenance: 2, other: 3 };
+    for (const [key, list] of [...devices.entries()].sort((a, b) => a[0].localeCompare(b[0]))) {
+        list.sort((a, b) => order[a.kind] - order[b.kind] || a.line.localeCompare(b.line));
+        lines.push(`\n## ${key} (${list.length} topic${list.length === 1 ? '' : 's'})`);
+        lines.push(...list.slice(0, cap).map((x) => x.line));
+        if (list.length > cap) lines.push(`… ${list.length - cap} more; describe_device "${key.split('/').pop()}" for all of them`);
+    }
+    if (variables.length) {
+        lines.push(`\n## variables (${variables.length})`);
+        lines.push(...variables.sort().slice(0, cap));
+        if (variables.length > cap) lines.push(`… ${variables.length - cap} more; search_mqtt_topics "${varPrefix}/status/#" with the room word`);
+    }
+    if (ctx.introspect?.scripts) {
+        const touches = (t) => roomTopics.has(t) || String(t).toLowerCase().includes(q);
+        const scripts = ctx.introspect
+            .scripts()
+            .map((sc) => {
+                const subs = [...sc.subscriptions, ...sc.varSubscriptions.map((k) => `${varPrefix}/status/${k}`)].filter(touches);
+                const pubs = sc.publishes.filter(touches);
+                return { label: sc.label, subs, pubs };
+            })
+            .filter((x) => x.subs.length || x.pubs.length || x.label.toLowerCase().includes(q))
+            .sort((a, b) => a.label.localeCompare(b.label));
+        if (scripts.length) {
+            lines.push(`\n## scripts (${scripts.length})`);
+            const some = (arr, n = 8) => (arr.length <= n ? arr.join(', ') : arr.slice(0, n).join(', ') + ` … (${arr.length})`);
+            for (const sc of scripts) {
+                const parts = [];
+                if (sc.subs.length) parts.push(`subscribes ${some(sc.subs)}`);
+                if (sc.pubs.length) parts.push(`publishes ${some(sc.pubs)}`);
+                lines.push(`- ${sc.label}${parts.length ? ': ' + parts.join('; ') : ''}`);
+            }
+        }
+    }
+    if (ctx.introspect?.devices) {
+        const devs = ctx.introspect.devices().filter(
+            (d) =>
+                String(d.name || d.id || '')
+                    .toLowerCase()
+                    .includes(q) || (d.refTopics || []).some((t) => roomTopics.has(t)),
+        );
+        if (devs.length) {
+            lines.push(`\n## Home Assistant discovery (${devs.length})`);
+            for (const d of devs)
+                lines.push(
+                    `- ${d.name || d.id}${d.orphaned ? ' (orphaned)' : ''}: ${(d.entities || []).map((e) => `${e.component || 'entity'} ${e.name || ''}`.trim()).join(', ') || 'no entities'}`,
+                );
+        }
+    }
+    return lines.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// run_analysis (roadmap I42, decision D-9): the model's code in a worker sandbox over read-only loaders
+// ---------------------------------------------------------------------------
+
+/** the loaders the sandbox may call, built from the tool context; each throws a readable error */
+function analysisLoaders(ctx) {
+    const store = ctx.store;
+    const needTime = (v, what) => {
+        const ms = parseTime(v);
+        if (Number.isNaN(ms)) throw new Error(`${what} must be ISO 8601 or relative ("-2h"); got ${v}`);
+        return ms;
+    };
+    return {
+        time: (str) => needTime(str, 'time'),
+        topics: (filter = '') => {
+            if (!store) throw new Error('the MQTT state store is not available');
+            const pattern = String(filter ?? '').trim();
+            const isFilter = /[+#]/.test(pattern);
+            const q = pattern.toLowerCase();
+            const out = [];
+            for (const [topic, obj] of store.mqttEntries()) {
+                if (isFilter ? !mqttWildcard(topic, pattern) : q && !topic.toLowerCase().includes(q)) continue;
+                out.push({ topic, value: obj.val, ts: obj.ts ?? null, lc: obj.lc ?? obj.ts ?? null });
+                if (out.length >= 5000) break;
+            }
+            return out;
+        },
+        history: async (topics, from = '-24h', to) => {
+            const resolved = resolveTopics({ topics }, store);
+            if (resolved.error) throw new Error(resolved.error);
+            if (!resolved.topics.length) throw new Error('history needs topics: a list or an MQTT filter');
+            const { influx, error } = influxForHistory();
+            if (error) throw new Error(error);
+            const fromMs = needTime(from, 'from');
+            const toMs = needTime(to, 'to');
+            const results = await Promise.all(resolved.topics.map((t) => fetchTopicSeries(influx, t, fromMs, toMs)));
+            const out = {};
+            results.forEach((r, i) => (out[resolved.topics[i]] = r.rows));
+            return out;
+        },
+        messages: async (topics, from = '-24h', to, limit = 1000) => {
+            const resolved = resolveTopics({ topics }, store, 20);
+            if (resolved.error) throw new Error(resolved.error);
+            if (!resolved.topics.length) throw new Error('messages needs topics: a list or an MQTT filter');
+            let client = null;
+            try {
+                client = require('../elastic').getClient();
+            } catch {
+                /* module missing */
+            }
+            if (!client) throw new Error('no Elasticsearch integration is configured in she (config "elastic"); use data.history (InfluxDB) for values over time instead');
+            const fromMs = needTime(from, 'from');
+            const toMs = needTime(to, 'to');
+            const cap = Math.min(Math.max(1, Number(limit) || 1000), 5000);
+            const res = await client.search({
+                index: ctx.elasticIndex || 'mqtt-*',
+                size: cap,
+                query: { bool: { filter: [{ terms: { topic: resolved.topics } }, { range: { '@timestamp': { gte: fromMs, lte: toMs } } }] } },
+                sort: [{ '@timestamp': { order: 'desc' } }],
+                _source: ['@timestamp', 'topic', 'payload'],
+            });
+            const hits = res?.hits?.hits ?? res?.body?.hits?.hits ?? [];
+            return hits.map((h) => {
+                const src = h._source || {};
+                const ts = typeof src['@timestamp'] === 'number' ? src['@timestamp'] : Date.parse(src['@timestamp']);
+                return { time: ts, topic: src.topic ?? '', payload: src.payload ?? '' };
+            });
+        },
+        log: async (filter = '', from, to, level = 'debug', limit = 500) => {
+            const fromMs = from ? needTime(from, 'from') : null;
+            const toMs = needTime(to, 'to');
+            const minRank = LEVEL_RANK[String(level).toLowerCase()] ?? 0;
+            const cap = Math.min(Math.max(1, Number(limit) || 500), 5000);
+            const matches = await collectLogEntries({ needle: String(filter ?? '').toLowerCase(), fromMs, toMs, minRank });
+            return matches.slice(-cap).map((e) => ({ ts: e.ts, level: e.level, msg: e.msg }));
+        },
+        script: (relPath) => {
+            const p = scriptPathOf(ctx.scriptDir, relPath);
+            if (!p) throw new Error(`"${relPath}" is not a script path`);
+            if (!fs.existsSync(p.abs)) throw new Error(`no script ${p.rel}`);
+            return fs.readFileSync(p.abs, 'utf8');
+        },
+    };
+}
+
+async function toolRunAnalysis({ code, from, to } = {}, ctx = {}) {
+    if (!code || typeof code !== 'string' || !code.trim()) return 'code is required: the body of an async function that returns the result.';
+    const { runAnalysis } = require('./ai-sandbox');
+    const cap = Math.max(500, Number(ctx.resultChars) || DEFAULT_RESULT_CHARS);
+    const r = await runAnalysis({ code, from, to }, analysisLoaders(ctx), { timeoutMs: ctx.analysisTimeoutMs });
+    const logText = r.logs.length ? `\nconsole (${r.logs.length} line${r.logs.length === 1 ? '' : 's'}):\n${r.logs.join('\n')}` : '';
+    let text;
+    let result = null;
+    if (r.error) text = `The analysis failed: ${r.error}${logText}`;
+    else {
+        const json = r.json ?? 'null';
+        result = json.length > cap ? json.slice(0, cap) + `\n… cut after ${cap} characters (${json.length} total); return less from the code.` : json;
+        text = `Result after ${r.ms} ms and ${r.calls} data call${r.calls === 1 ? '' : 's'}:\n${result}${logText}`;
+    }
+    return { text, event: { type: 'analysis', code, result, error: r.error || null, logs: r.logs, ms: r.ms } };
+}
+
 function toolListServices({ filter = '' } = {}, ctx = {}) {
     if (!ctx.introspect?.instances) return NO_INTROSPECT;
     const q = String(filter).toLowerCase();
@@ -1087,6 +1608,19 @@ async function toolSheFetch({ url }, ctx = {}) {
     return `Content of ${url}:\n\n${truncated}`;
 }
 
+/** get_mqtt_topic with "topics" (roadmap I39): a list or one filter, one line per topic */
+function toolGetMqttTopics(args, store) {
+    const { topics, topic } = args || {};
+    const hasList = Array.isArray(topics) ? topics.length > 0 : typeof topics === 'string' && topics.trim() !== '';
+    if (!hasList) return toolGetMqttTopic({ topic }, store);
+    if (!store) return 'MQTT state store not available.';
+    const resolved = resolveTopics({ topics }, store);
+    if (resolved.error) return resolved.error;
+    const out = resolved.topics.map((t) => toolGetMqttTopic({ topic: t }, store));
+    if (resolved.note) out.push(resolved.note);
+    return out.join('\n');
+}
+
 function toolGetMqttTopic({ topic }, store) {
     if (!store) return 'MQTT state store not available.';
     if (!topic || typeof topic !== 'string') return 'topic argument is required.';
@@ -1228,5 +1762,21 @@ module.exports = {
     TOOL_DEFINITIONS,
     TOOL_DEFINITIONS_ANTHROPIC,
     executeTool,
-    _internal: { isPrivateAddress, isLocalName, parseDuration, valueMatcher, pageOf, parseTime, measurementCandidates, thinSeries, publishRefusal, scriptPathOf },
+    _internal: {
+        isPrivateAddress,
+        isLocalName,
+        parseDuration,
+        valueMatcher,
+        pageOf,
+        parseTime,
+        measurementCandidates,
+        thinSeries,
+        publishRefusal,
+        scriptPathOf,
+        resolveTopics,
+        fetchTopicSeries,
+        influxForHistory,
+        gapStr,
+        commonTopicPrefix,
+    },
 };