smart-home-engine 0.12.0 → 0.14.0

package/src/web/ai-tools.js

@@ -0,0 +1,210 @@
+'use strict';
+
+/**
+ * AI tool definitions and executor for the she AI assistant.
+ *
+ * Available tools:
+ *   search_mqtt_topics  — fuzzy-search known MQTT topics in the state store
+ *   read_script         — read a script file from the scripts directory
+ *   get_script_logs     — retrieve recent log entries, optionally filtered by script name
+ *   she_fetch           — fetch a URL and return its text content
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { getLogBuffer } = require('./log-ws');
+
+// ---------------------------------------------------------------------------
+// Tool schemas
+// ---------------------------------------------------------------------------
+
+/** Tool definitions in OpenAI function-calling format. */
+const TOOL_DEFINITIONS = [
+    {
+        type: 'function',
+        function: {
+            name: 'search_mqtt_topics',
+            description:
+                '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.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    query: {
+                        type: 'string',
+                        description: 'Case-insensitive substring to match against topic names. Pass empty string to list all topics (capped at 50).',
+                    },
+                },
+                required: ['query'],
+            },
+        },
+    },
+    {
+        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.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    path: {
+                        type: 'string',
+                        description: 'Script file path relative to the scripts directory, e.g. "lights.js" or "lib/utils.js".',
+                    },
+                },
+                required: ['path'],
+            },
+        },
+    },
+    {
+        type: 'function',
+        function: {
+            name: 'get_script_logs',
+            description:
+                'Retrieve recent log messages from the she daemon. ' +
+                'Filter by script name to diagnose errors or trace what a specific script has been doing.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    script_name: {
+                        type: 'string',
+                        description: 'Filter log lines to those mentioning this script name (file name without extension). Pass empty string to get all recent logs.',
+                    },
+                    limit: {
+                        type: 'integer',
+                        description: 'Maximum number of log lines to return (1-200, default 50).',
+                    },
+                },
+                required: [],
+            },
+        },
+    },
+    {
+        type: 'function',
+        function: {
+            name: 'she_fetch',
+            description:
+                'Fetch the content of a URL and return it as plain text. ' +
+                'Use this to retrieve documentation, data sheets, or any web resource relevant to the user request. ' +
+                'HTML is stripped to plain text automatically.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    url: {
+                        type: 'string',
+                        description: 'The URL to fetch (http or https).',
+                    },
+                },
+                required: ['url'],
+            },
+        },
+    },
+];
+
+/** Same definitions in Anthropic tool format. */
+const TOOL_DEFINITIONS_ANTHROPIC = TOOL_DEFINITIONS.map((t) => ({
+    name: t.function.name,
+    description: t.function.description,
+    input_schema: t.function.parameters,
+}));
+
+// ---------------------------------------------------------------------------
+// Executor
+// ---------------------------------------------------------------------------
+
+/**
+ * Execute a named tool and return its result as a plain string.
+ * @param {string} name  — tool function name
+ * @param {object} args  — parsed arguments from LLM
+ * @param {{ store: import('../lib/state-store')|null, scriptDir: string|null }} ctx
+ * @returns {string}
+ */
+async function executeTool(name, args, ctx) {
+    try {
+        switch (name) {
+            case 'search_mqtt_topics': return toolSearchMqttTopics(args, ctx.store);
+            case 'read_script':        return toolReadScript(args, ctx.scriptDir);
+            case 'get_script_logs':    return toolGetScriptLogs(args);
+            case 'she_fetch':          return await toolSheFetch(args);
+            default:                   return `Unknown tool: ${name}`;
+        }
+    } catch (e) {
+        return `Tool error (${name}): ${e.message}`;
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Individual tools
+// ---------------------------------------------------------------------------
+
+function toolSearchMqttTopics({ query = '' }, store) {
+    if (!store) return 'MQTT state store not available.';
+    const q = query.toLowerCase();
+    const results = [];
+    for (const [topic, obj] of store.mqttEntries()) {
+        if (!q || topic.toLowerCase().includes(q)) {
+            results.push(`${topic}: ${JSON.stringify(obj.val)}`);
+            if (results.length >= 50) {
+                results.push('… (truncated to 50 results, use a more specific query)');
+                break;
+            }
+        }
+    }
+    if (results.length === 0) {
+        return q ? `No MQTT topics found matching "${query}".` : 'No MQTT topics tracked yet.';
+    }
+    return `Found ${results.length} topic(s):\n${results.join('\n')}`;
+}
+
+function toolReadScript({ path: relPath }, scriptDir) {
+    if (!scriptDir) return 'Scripts directory not configured.';
+    if (!relPath || typeof relPath !== 'string') return 'path argument is required.';
+    const abs = path.resolve(scriptDir, relPath.replace(/^\/+/, ''));
+    // Path traversal guard
+    if (!abs.startsWith(scriptDir + path.sep) && abs !== scriptDir) {
+        return 'Access denied: path escapes the scripts directory.';
+    }
+    if (!fs.existsSync(abs)) return `File not found: ${relPath}`;
+    const content = fs.readFileSync(abs, 'utf8');
+    return `## ${relPath}\n\`\`\`javascript\n${content}\n\`\`\``;
+}
+
+function toolGetScriptLogs({ script_name = '', limit = 50 }) {
+    const cap = Math.min(Math.max(1, Number(limit) || 50), 200);
+    const buf = getLogBuffer();
+    const needle = String(script_name).toLowerCase();
+    const filtered = needle ? buf.filter((e) => e.msg.toLowerCase().includes(needle)) : buf;
+    const recent = filtered.slice(-cap);
+    if (recent.length === 0) {
+        return needle ? `No log entries found mentioning "${script_name}".` : 'No log entries in buffer yet.';
+    }
+    return recent
+        .map((e) => {
+            const t = new Date(e.ts).toISOString().slice(11, 19);
+            return `[${t}] ${e.level.toUpperCase()} ${e.msg}`;
+        })
+        .join('\n');
+}
+
+const MAX_FETCH_CHARS = 8000;
+
+async function toolSheFetch({ url }) {
+    if (!url || typeof url !== 'string') return 'url argument is required.';
+    if (!/^https?:\/\//i.test(url)) return 'Only http and https URLs are supported.';
+    const res = await fetch(url, {
+        headers: { 'User-Agent': 'she-ai-agent/1.0' },
+        signal: AbortSignal.timeout(15000),
+    });
+    if (!res.ok) return `HTTP error ${res.status} ${res.statusText} fetching ${url}`;
+    const ct = res.headers.get('content-type') || '';
+    const text = await res.text();
+    // Strip HTML tags for cleaner text
+    const plain = ct.includes('html') ? text.replace(/<[^>]+>/g, ' ').replace(/\s+/g, ' ').trim() : text;
+    const truncated = plain.length > MAX_FETCH_CHARS ? plain.slice(0, MAX_FETCH_CHARS) + `\n… (truncated, ${plain.length} chars total)` : plain;
+    return `Content of ${url}:\n\n${truncated}`;
+}
+
+module.exports = { TOOL_DEFINITIONS, TOOL_DEFINITIONS_ANTHROPIC, executeTool };

package/src/web/log-ws.js

@@ -5,6 +5,10 @@ const { WebSocketServer } = require('ws');
 let _wss = null;
 const _clients = new Set();
 
+// Ring buffer of recent log entries for the AI tool get_script_logs
+const _logBuffer = [];
+const LOG_BUFFER_MAX = 500;
+
 /**
  * Attach a WebSocketServer to an existing http.Server.
  * Clients connect to /she/ws. Once connected they receive:
@@ -54,12 +58,23 @@ function broadcast(msg) {
 
 /**
  * Broadcast a structured log entry to all connected WebSocket clients.
+ * Also stores the entry in the in-memory ring buffer.
  * @param {{ level: string, msg: string, ts: number }} entry
  */
 function broadcastLog(entry) {
+    _logBuffer.push(entry);
+    if (_logBuffer.length > LOG_BUFFER_MAX) _logBuffer.shift();
     broadcast({ type: 'log', ...entry });
 }
 
+/**
+ * Return a snapshot of recent log entries (newest last).
+ * @returns {{ level: string, msg: string, ts: number }[]}
+ */
+function getLogBuffer() {
+    return _logBuffer.slice();
+}
+
 /**
  * Close the WebSocket server.
  * @returns {Promise<void>}
@@ -75,4 +90,4 @@ function closeWss() {
     });
 }
 
-module.exports = { attachWss, broadcast, broadcastLog, closeWss };
+module.exports = { attachWss, broadcast, broadcastLog, closeWss, getLogBuffer };

package/src/web/matter-api.js

@@ -63,8 +63,13 @@ router.post('/commission', async (req, res) => {
 router.get('/devices/:nodeId', (req, res) => {
     if (!isReady()) return notReady(res);
     try {
-        const endpoints = getController().getEndpoints(req.params.nodeId);
-        res.json({ nodeId: req.params.nodeId, endpoints });
+        const ctrl = getController();
+        const endpoints = ctrl.getEndpoints(req.params.nodeId);
+        // Derive device-level name and subtitle from the root endpoint (0)
+        const rootEp = endpoints.find(ep => ep.endpointId === 0);
+        const name = rootEp?.name ?? endpoints.find(ep => ep.name)?.name ?? null;
+        const subtitle = ctrl.getDeviceSubtitle(req.params.nodeId);
+        res.json({ nodeId: req.params.nodeId, endpoints, name, subtitle });
     } catch (err) {
         if (err.message.includes('not found')) return res.status(404).json({ error: err.message });
         res.status(500).json({ error: err.message });

package/src/web/prompts/db-doc.md

@@ -0,0 +1,17 @@
+You are SHE Assistant, helping manage sheDB documents for she (smart-home-engine).
+
+sheDB is a simple JSON document store. Each document has a string ID (structured like an MQTT topic path, e.g. `devices/lamp1`) and a JSON value (any object, array, or scalar).
+
+When proposing a new or updated document, output the document ID and the JSON content in this format:
+
+```json
+// @doc-id: devices/lamp1
+{
+  "name": "Living room lamp",
+  "type": "light"
+}
+```
+
+The `// @doc-id:` comment must be the very first line inside the JSON block — the UI uses it to pre-fill the document ID field.
+
+Document IDs follow MQTT topic conventions: use `/` as separator, lowercase, no spaces.

package/src/web/prompts/db-view.md

@@ -0,0 +1,30 @@
+You are SHE Assistant, helping write sheDB MapReduce view definitions for she (smart-home-engine).
+
+A view has three optional parts:
+
+1. **Filter** — an MQTT-style topic wildcard that selects which document IDs enter the view. Plain string, no code.
+   MQTT wildcards: `+` matches exactly one path segment, `#` matches any number of segments (must be last).
+   Examples: `devices/+/state` matches `devices/lamp1/state`.  `sensors/#` matches all IDs starting with `sensors/`.
+   ⚠️  `*` is NOT a valid MQTT wildcard — never use it. Use `#` for "match everything".
+
+2. **Map** — a JavaScript function body. `this` is the current document. Call `emit(value)` to include a value in the result array. No `return`.
+
+3. **Reduce** — a JavaScript function body that receives `result` (the array from map) and must `return` a transformed value.
+
+When proposing view parts, use these exact formats (include only the parts that change):
+
+```filter
+devices/#
+```
+
+```javascript
+// @view-map
+if (this.temperature !== undefined) emit(this.temperature);
+```
+
+```javascript
+// @view-reduce
+return result.reduce((a, b) => a + b, 0) / result.length;
+```
+
+Keep the `// @view-map` / `// @view-reduce` comment as the very first line of each block — the UI uses it to detect which field to fill in.

package/src/web/prompts/scripts-base.md

@@ -0,0 +1,18 @@
+You are SHE Assistant, an expert AI pair programmer for she (smart-home-engine).
+she is a Node.js daemon that runs user JavaScript scripts in a sandboxed VM for home automation.
+When proposing changes to a script, always output the COMPLETE new file content in a single fenced ```javascript code block. Never output partial diffs or fragments — the user applies the full file at once.
+Keep any existing header comments and the 'use strict'; directive.
+When the user asks you to CREATE a new script (not modify the current one), place a special hint as the very first line INSIDE the code block (right after the opening ```javascript fence line), like this:
+
+```javascript
+// @new-file: descriptive-name.js
+/* global she */
+'use strict';
+// ... rest of script
+```
+
+Use a short kebab-case filename. Do NOT put the hint outside or before the code block. The UI will detect it and offer to save the file.
+
+### MQTT publishing rules
+When sending a command to a device (e.g. turning a light on/off, triggering an action), ALWAYS use `she.mqtt.pub()` WITHOUT retain — never set `retain: true` on command topics.
+Only use `she.mqtt.set()` or `retain: true` for storing persistent state or configuration values that must survive restarts, not for commands.

package/src/web/prompts/she-api-ref.md

@@ -0,0 +1,73 @@
+## she sandbox API
+
+Scripts run in a sandboxed VM. The `she` object is injected automatically.
+
+### Script conventions
+- First lines: /* global she */ then 'use strict';
+- No require() — the module system is not available
+- All subscriptions and schedules persist across reconnects
+
+### MQTT
+```
+she.mqtt.sub(topic, [opts], cb)        Subscribe; wildcards: + (1 level) # (multi)
+                                         +//sensor  →  +/status/sensor shorthand
+                                         opts.change: true = only fire when value changes
+she.mqtt.pub(topic, payload, [opts])   Publish; opts: { qos, retain }
+she.mqtt.get(topic)                    Current retained value (sync)
+she.mqtt.set(topic, val)               Publish as retained
+she.mqtt.link(src, target, [fn])       Forward src changes to target; optional transform
+she.mqtt.age(topic)                    Seconds since topic last received a message
+she.mqtt.on('connect'|'disconnect', cb) MQTT lifecycle events
+```
+
+### Scheduling
+```
+she.schedule(pattern, [opts], cb)
+  pattern: cron string | Date | suncalc event name
+  suncalc events: 'sunrise' 'sunset' 'dawn' 'dusk'
+                  'nauticalDawn' 'nauticalDusk' 'solarNoon' 'night'
+  opts.shift:  seconds offset (e.g. -1800 = 30 min before event)
+  opts.random: max random delay in seconds added to the trigger time
+```
+
+### Universal key-value API
+```
+she.on(key, cb)        Subscribe. Key prefixes: mqtt::  var::  matter::
+she.set(key, val)      Set value (mqtt:: or var:: namespaces)
+she.get(key)           Current value
+she.getObject(key)     Current { val, ts, lc } state object
+```
+
+### Variable system (var:: namespace)
+Topics prefixed with "var" (default) are persisted as retained MQTT messages
+and available across scripts via she.get('var::name') / she.set('var::name', v).
+
+### sheDB
+```
+she.db.get(id)                      Get document (undefined if not found)
+she.db.set(id, doc)                 Create or overwrite document
+she.db.extend(id, partial)          Deep-merge partial into existing document
+she.db.delete(id)                   Delete document
+she.db.sub(pattern, cb)             Subscribe to document changes (MQTT wildcard)
+she.db.query(filter, mapFn, [reduceFn])  Synchronous ad-hoc query → Array
+```
+
+### Matter
+```
+she.matter.sub(nodeId, endpointId, cluster, attr, cb)    Subscribe to attribute
+she.matter.unsub(listenerId)
+she.matter.get(nodeId, endpointId, cluster, attr)         → Promise<value>
+she.matter.send(nodeId, endpointId, cluster, cmd, [args]) → Promise<result>
+```
+
+### Helpers
+```
+she.timer(src, target, ms)           Pulse target=1 for ms after src goes truthy
+she.combineBool(srcs[], target)      Publish OR of source values to target
+she.combineMax(srcs[], target)       Publish maximum of source values to target
+she.link(src, target, [fn])          Alias for she.mqtt.link
+she.age(topic)                       Alias for she.mqtt.age
+she.now()                            Current timestamp in ms
+she.debug / .info / .warn / .error   Structured logging (prefixed with script name)
+she.global                           Shared mutable object across all scripts
+```

package/src/web/scripts-api.js

@@ -28,7 +28,7 @@ function hasShelibMarker(absDir) {
     return fs.existsSync(path.join(absDir, '.shelib'));
 }
 
-/** Flat list of all .js files with metadata and lib flag. */
+/** Flat list of all files with metadata and lib flag. */
 function walk(dir, base, parentIsLib) {
     let entries;
     try {
@@ -43,7 +43,7 @@ function walk(dir, base, parentIsLib) {
         const rel = base ? `${base}/${entry.name}` : entry.name;
         if (entry.isDirectory()) {
             results.push(...walk(path.join(dir, entry.name), rel, lib));
-        } else if (entry.name.endsWith('.js')) {
+        } else {
             const stat = fs.statSync(path.join(dir, entry.name));
             results.push({ path: rel, size: stat.size, mtime: stat.mtimeMs, lib });
         }
@@ -52,7 +52,7 @@ function walk(dir, base, parentIsLib) {
 }
 
 /**
- * Nested tree of all .js files and subdirectories.
+ * Nested tree of all files and subdirectories.
  * Each node: { type:'file'|'dir', name, path, lib, size?, mtime?, children? }
  */
 function buildTree(dir, base, parentIsLib) {
@@ -73,7 +73,7 @@ function buildTree(dir, base, parentIsLib) {
             const childIsLib = lib || hasShelibMarker(abs);
             const children = buildTree(abs, rel, childIsLib);
             result.push({ type: 'dir', name: entry.name, path: rel, lib: childIsLib, children });
-        } else if (entry.name.endsWith('.js')) {
+        } else {
             const stat = fs.statSync(abs);
             result.push({ type: 'file', name: entry.name, path: rel, lib, size: stat.size, mtime: stat.mtimeMs });
         }
@@ -120,10 +120,6 @@ router.use((req, res) => {
     if (method === 'PUT') {
         const abs = safePath(root, filePath);
         if (!abs) return res.status(400).json({ error: 'Invalid path' });
-        const basename = path.basename(abs);
-        if (!basename.endsWith('.js') && basename !== '.shelib') {
-            return res.status(400).json({ error: 'Only .js and .shelib files are allowed' });
-        }
         const content = typeof req.body?.content === 'string' ? req.body.content : null;
         if (content === null) return res.status(400).json({ error: 'Missing body.content string' });
         try {

package/src/web/server.js

@@ -58,6 +58,13 @@ app.post('/she/restart', (req, res) => {
     setTimeout(() => process.exit(0), 200);
 });
 
+// Runtime stats — script count + MQTT topic count
+let _getStats = null;
+function setStatsProvider(fn) { _getStats = fn; }
+app.get('/she/status', (req, res) => {
+    res.json(_getStats ? _getStats() : { scripts: 0, topics: 0 });
+});
+
 // Serve the built Svelte SPA from dist/web/
 // Hashed assets (JS/CSS) are immutable; index.html must never be cached so
 // browsers always pick up a freshly deployed version.
@@ -136,4 +143,4 @@ function stopServer() {
     });
 }
 
-module.exports = { app, registerRoute, startServer, stopServer };
+module.exports = { app, registerRoute, setStatsProvider, startServer, stopServer };