smart-home-engine 0.14.0 → 0.16.0

package/src/web/ai-api.js

@@ -91,8 +91,8 @@ async function callOpenAICompat(config, messages, tools) {
           }
         : undefined;
 
-    // Detect tool call response
-    if (choice?.finish_reason === 'tool_calls' && choice.message?.tool_calls?.length) {
+    // Detect tool call response — some models return finish_reason 'stop' even with tool calls
+    if (choice?.message?.tool_calls?.length) {
         return { toolCalls: choice.message.tool_calls, assistantMsg: choice.message, usage };
     }
 
@@ -174,22 +174,22 @@ async function resolveAndGetAnswer(ai, messages, toolContext, onEvent) {
     const isAnthropic = ai.provider === 'anthropic';
     const tools = isAnthropic ? TOOL_DEFINITIONS_ANTHROPIC : TOOL_DEFINITIONS;
     let msgs = messages;
+    let toolsUsed = false; // once the model has used tools, stop offering them
 
     for (let round = 0; round < 6; round++) {
-        // On the final safety round, don't send tools to avoid infinite loops
-        const roundTools = round < 5 ? tools : undefined;
+        // After the first round of tool calls, don't offer tools again.
+        // This forces a plain-text response rather than letting the model
+        // keep calling tools indefinitely (and some models return empty
+        // content when given tools but no reason to call them).
+        const roundTools = toolsUsed ? undefined : tools;
 
         let result;
         try {
-            result = isAnthropic
-                ? await callAnthropic(ai, msgs, roundTools)
-                : await callOpenAICompat(ai, msgs, roundTools);
+            result = isAnthropic ? await callAnthropic(ai, msgs, roundTools) : await callOpenAICompat(ai, msgs, roundTools);
         } catch (e) {
             if (round === 0 && roundTools) {
                 // Model may not support tool calling — retry without tools
-                result = isAnthropic
-                    ? await callAnthropic(ai, msgs)
-                    : await callOpenAICompat(ai, msgs);
+                result = isAnthropic ? await callAnthropic(ai, msgs) : await callOpenAICompat(ai, msgs);
             } else {
                 throw e;
             }
@@ -197,12 +197,21 @@ async function resolveAndGetAnswer(ai, messages, toolContext, onEvent) {
 
         // No tool calls → we have the final answer
         if (!result.toolCalls?.length) {
+            // If the model returned empty content after using tools, nudge it once
+            if (!result.message && toolsUsed) {
+                const nudgeMsgs = [...msgs, { role: 'user', content: 'Based on the information retrieved above, please now provide your complete response.' }];
+                const nudged = isAnthropic ? await callAnthropic(ai, nudgeMsgs) : await callOpenAICompat(ai, nudgeMsgs);
+                return { message: nudged.message ?? '', usage: nudged.usage };
+            }
             return { message: result.message ?? '', usage: result.usage };
         }
 
         // Execute tool calls and append results to message history
+        toolsUsed = true;
         if (isAnthropic) {
-            msgs = [...msgs, { role: 'assistant', content: result.assistantMsg }];
+            // Strip text blocks when tool_use blocks are present (same draft-reproduction issue)
+            const anthropicAssistantContent = result.assistantMsg.some((b) => b.type === 'tool_use') ? result.assistantMsg.filter((b) => b.type !== 'text') : result.assistantMsg;
+            msgs = [...msgs, { role: 'assistant', content: anthropicAssistantContent }];
             const toolResultBlocks = [];
             for (const tc of result.toolCalls) {
                 const args = tc.input || {};
@@ -213,11 +222,19 @@ async function resolveAndGetAnswer(ai, messages, toolContext, onEvent) {
             }
             msgs = [...msgs, { role: 'user', content: toolResultBlocks }];
         } else {
-            msgs = [...msgs, { ...result.assistantMsg, role: 'assistant' }];
+            // Strip any draft content alongside tool_calls — if kept, the model reproduces
+            // the (hallucinated) draft in round 1 instead of using the tool results.
+            const assistantEntry = { ...result.assistantMsg, role: 'assistant' };
+            if (assistantEntry.content && assistantEntry.tool_calls?.length) assistantEntry.content = null;
+            msgs = [...msgs, assistantEntry];
             for (const tc of result.toolCalls) {
                 const name = tc.function.name;
                 let args;
-                try { args = JSON.parse(tc.function.arguments || '{}'); } catch { args = {}; }
+                try {
+                    args = JSON.parse(tc.function.arguments || '{}');
+                } catch {
+                    args = {};
+                }
                 onEvent?.({ type: 'tool_call', name, args });
                 const content = await executeTool(name, args, toolContext);
                 onEvent?.({ type: 'tool_result', name, content });
@@ -227,9 +244,7 @@ async function resolveAndGetAnswer(ai, messages, toolContext, onEvent) {
     }
 
     // Fallback (should not normally be reached)
-    const fallback = isAnthropic
-        ? await callAnthropic(ai, msgs)
-        : await callOpenAICompat(ai, msgs);
+    const fallback = isAnthropic ? await callAnthropic(ai, msgs) : await callOpenAICompat(ai, msgs);
     return { message: fallback.message ?? '', usage: fallback.usage };
 }
 
@@ -358,7 +373,10 @@ router.get('/models', async (req, res) => {
             const r = await fetch(`${base}/api/tags`);
             if (!r.ok) throw new Error(`Ollama /api/tags returned ${r.status}`);
             const json = await r.json();
-            const models = (json.models || []).map((m) => m.name || m.model).filter(Boolean).sort();
+            const models = (json.models || [])
+                .map((m) => m.name || m.model)
+                .filter(Boolean)
+                .sort();
             return res.json({ models });
         } else if (ai.provider === 'anthropic') {
             return res.json({ models: [] }); // no public list endpoint
@@ -369,7 +387,10 @@ router.get('/models', async (req, res) => {
             const r = await fetch(`${base}/v1/models`, { headers: h });
             if (!r.ok) throw new Error(`/v1/models returned ${r.status}`);
             const json = await r.json();
-            const models = (json.data || []).map((m) => m.id).filter(Boolean).sort();
+            const models = (json.data || [])
+                .map((m) => m.id)
+                .filter(Boolean)
+                .sort();
             return res.json({ models });
         }
     } catch (e) {
@@ -385,7 +406,7 @@ router.get('/model-info', async (req, res) => {
     if (ai.provider !== 'ollama') return res.status(400).json({ error: 'Model info is only available for Ollama' });
 
     const base = (ai.baseUrl || 'http://localhost:11434').replace(/\/$/, '');
-    const model = (typeof req.query.model === 'string' && req.query.model) ? req.query.model : ai.model;
+    const model = typeof req.query.model === 'string' && req.query.model ? req.query.model : ai.model;
 
     const [versionRes, showRes, psRes] = await Promise.allSettled([
         fetch(`${base}/api/version`).then((r) => r.json()),
@@ -400,10 +421,21 @@ router.get('/model-info', async (req, res) => {
     res.json({
         version: versionRes.status === 'fulfilled' ? versionRes.value.version : null,
         details: showRes.status === 'fulfilled' ? showRes.value.details : null,
-        running: psRes.status === 'fulfilled' ? (psRes.value.models || []) : null,
+        running: psRes.status === 'fulfilled' ? psRes.value.models || [] : null,
     });
 });
 
+// POST /she/ai/prompt — return the current system prompt for preview
+router.post('/prompt', (req, res) => {
+    const { context = {}, currentScript, currentView, currentDoc, extraFiles } = req.body || {};
+    try {
+        const prompt = buildSystemPrompt(context, currentScript ?? null, currentView ?? null, currentDoc ?? null, _store, extraFiles || []);
+        res.json({ prompt });
+    } catch (e) {
+        res.status(500).json({ error: e.message });
+    }
+});
+
 // POST /she/ai/chat — non-streaming
 router.post('/chat', async (req, res) => {
     const ai = readAiConfig(req.app.locals.configPath);
@@ -411,11 +443,11 @@ router.post('/chat', async (req, res) => {
         return res.status(400).json({ error: 'AI provider not configured. Set ai.provider and ai.model in Config.' });
     }
 
-    const { messages = [], currentScript, currentView, currentDoc, context = {}, modelOverride } = req.body || {};
+    const { messages = [], currentScript, currentView, currentDoc, context = {}, modelOverride, extraFiles } = req.body || {};
     if (!Array.isArray(messages)) return res.status(400).json({ error: 'messages must be an array' });
 
-    const aiWithModel = (modelOverride && typeof modelOverride === 'string') ? { ...ai, model: modelOverride } : ai;
-    const systemPrompt = buildSystemPrompt(context, currentScript ?? null, currentView ?? null, currentDoc ?? null, _store);
+    const aiWithModel = modelOverride && typeof modelOverride === 'string' ? { ...ai, model: modelOverride } : ai;
+    const systemPrompt = buildSystemPrompt(context, currentScript ?? null, currentView ?? null, currentDoc ?? null, _store, extraFiles || []);
     const fullMessages = [{ role: 'system', content: systemPrompt }, ...messages];
 
     try {
@@ -441,10 +473,18 @@ router.post('/chat/stream', async (req, res) => {
         return res.status(400).json({ error: 'AI provider not configured. Set ai.provider and ai.model in Config.' });
     }
 
-    const { messages = [], currentScript, currentView, currentDoc, context = {}, modelOverride } = req.body || {};
+    const { messages = [], currentScript, currentView, currentDoc, context = {}, modelOverride, extraFiles } = req.body || {};
     if (!Array.isArray(messages)) return res.status(400).json({ error: 'messages must be an array' });
 
-    const aiWithModel = (modelOverride && typeof modelOverride === 'string') ? { ...ai, model: modelOverride } : ai;
+    const aiWithModel = modelOverride && typeof modelOverride === 'string' ? { ...ai, model: modelOverride } : ai;
+
+    // Build system prompt BEFORE flushing headers so errors can still return a proper HTTP status
+    let systemPrompt;
+    try {
+        systemPrompt = buildSystemPrompt(context, currentScript ?? null, currentView ?? null, currentDoc ?? null, _store, extraFiles || []);
+    } catch (e) {
+        return res.status(500).json({ error: `Failed to build system prompt: ${e.message}` });
+    }
 
     res.set({
         'Content-Type': 'text/event-stream',
@@ -455,7 +495,6 @@ router.post('/chat/stream', async (req, res) => {
 
     const send = (data) => res.write(`data: ${JSON.stringify(data)}\n\n`);
 
-    const systemPrompt = buildSystemPrompt(context, currentScript ?? null, currentView ?? null, currentDoc ?? null, _store);
     const fullMessages = [{ role: 'system', content: systemPrompt }, ...messages];
 
     try {

package/src/web/ai-context.js

@@ -15,9 +15,9 @@ const path = require('path');
 // Load prompt templates once at startup — plain Markdown files, no escaping needed
 const P = path.join(__dirname, 'prompts');
 const SCRIPTS_BASE_PROMPT = fs.readFileSync(path.join(P, 'scripts-base.md'), 'utf8').trim();
-const SHE_API_REF         = fs.readFileSync(path.join(P, 'she-api-ref.md'),  'utf8').trim();
-const DB_VIEW_PROMPT      = fs.readFileSync(path.join(P, 'db-view.md'),       'utf8').trim();
-const DB_DOC_PROMPT       = fs.readFileSync(path.join(P, 'db-doc.md'),        'utf8').trim();
+const SHE_API_REF = fs.readFileSync(path.join(P, 'she-api-ref.md'), 'utf8').trim();
+const DB_VIEW_PROMPT = fs.readFileSync(path.join(P, 'db-view.md'), 'utf8').trim();
+const DB_DOC_PROMPT = fs.readFileSync(path.join(P, 'db-doc.md'), 'utf8').trim();
 
 /**
  * Build the full system prompt, including optional context sections.
@@ -30,9 +30,9 @@ const DB_DOC_PROMPT       = fs.readFileSync(path.join(P, 'db-doc.md'),        'u
  * @param {import('../lib/state-store') | null} store
  * @returns {string}
  */
-function buildSystemPrompt(requestCtx, currentScript, currentView, currentDoc, store) {
-    const isViewMode = !!(currentView?.id);
-    const isDocMode  = !!(currentDoc?.id);
+function buildSystemPrompt(requestCtx, currentScript, currentView, currentDoc, store, extraFiles) {
+    const isViewMode = !!currentView?.id;
+    const isDocMode = !!currentDoc?.id;
 
     let basePrompt;
     if (isViewMode) {
@@ -54,10 +54,10 @@ function buildSystemPrompt(requestCtx, currentScript, currentView, currentDoc, s
     }
 
     if (currentView?.id) {
-        const filterStr  = (currentView.filter || '').trim();
-        const mapBody    = (currentView.map    || '').trim();
+        const filterStr = (currentView.filter || '').trim();
+        const mapBody = (currentView.map || '').trim();
         const reduceBody = (currentView.reduce || '').trim();
-        const viewLines  = [`## Current view: ${currentView.id}`];
+        const viewLines = [`## Current view: ${currentView.id}`];
         viewLines.push(`Filter: ${filterStr || '(none)'}`);
         viewLines.push(`Map:\n\`\`\`javascript\n${mapBody || '// (empty)'}\n\`\`\``);
         if (reduceBody) {
@@ -69,26 +69,10 @@ function buildSystemPrompt(requestCtx, currentScript, currentView, currentDoc, s
     }
 
     if (currentDoc?.id) {
-        const content = typeof currentDoc.content === 'string'
-            ? currentDoc.content
-            : JSON.stringify(currentDoc.content, null, 2);
+        const content = typeof currentDoc.content === 'string' ? currentDoc.content : JSON.stringify(currentDoc.content, null, 2);
         parts.push(`## Current document: ${currentDoc.id}\n\`\`\`json\n${content}\n\`\`\``);
     }
 
-    if (requestCtx.mqtt && store) {
-        const topics = [];
-        for (const [topic, obj] of store.mqttEntries()) {
-            topics.push(`${topic}: ${JSON.stringify(obj.val)}`);
-            if (topics.length >= 100) {
-                topics.push('… (truncated)');
-                break;
-            }
-        }
-        if (topics.length > 0) {
-            parts.push(`## Current MQTT state\n${topics.join('\n')}`);
-        }
-    }
-
     if (requestCtx.shedb) {
         try {
             const core = require('./shedb').getCore();
@@ -118,18 +102,11 @@ function buildSystemPrompt(requestCtx, currentScript, currentView, currentDoc, s
         }
     }
 
-    if (requestCtx.matter) {
-        try {
-            const controller = require('../matter/controller');
-            if (typeof controller.listPaired === 'function') {
-                const nodes = controller.listPaired();
-                if (nodes.length > 0) {
-                    const list = nodes.map((n) => `  nodeId ${n.nodeId}: ${n.label || 'unnamed'}`).join('\n');
-                    parts.push(`## Paired Matter devices\n${list}`);
-                }
-            }
-        } catch {
-            // matter not initialised — skip silently
+    if (extraFiles && extraFiles.length > 0) {
+        for (const f of extraFiles) {
+            const ext = (f.name.match(/\.([^.]+)$/) || [])[1] || '';
+            const lang = ext.toLowerCase();
+            parts.push(`## Attached file: ${f.name}\n\`\`\`${lang}\n${f.content}\n\`\`\``);
         }
     }
 

package/src/web/ai-tools.js

@@ -27,7 +27,8 @@ const TOOL_DEFINITIONS = [
             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.',
+                'Use this to discover real topic names before writing scripts. ' +
+                'Homematic related topics (under the topic tree hm/) end with STATE for switching actuators and with LEVEL for dimmers.',
             parameters: {
                 type: 'object',
                 properties: {
@@ -44,9 +45,7 @@ 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 the content of a script file from the she scripts directory. ' + 'Use this to review existing scripts before suggesting changes.',
             parameters: {
                 type: 'object',
                 properties: {
@@ -63,9 +62,7 @@ const TOOL_DEFINITIONS = [
         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.',
+            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: {
@@ -102,6 +99,73 @@ const TOOL_DEFINITIONS = [
             },
         },
     },
+    {
+        type: 'function',
+        function: {
+            name: 'get_mqtt_topic',
+            description:
+                'Get the current value and timestamps of a specific MQTT topic from the she state store. ' + 'Use this when you need the exact current state of a known topic.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    topic: {
+                        type: 'string',
+                        description: 'The exact MQTT topic path, e.g. "home/livingroom/light/state".',
+                    },
+                },
+                required: ['topic'],
+            },
+        },
+    },
+    {
+        type: 'function',
+        function: {
+            name: 'list_shedb_docs',
+            description: 'List document IDs in the sheDB document store. ' + 'Use this to discover what documents exist before fetching their content.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    filter: {
+                        type: 'string',
+                        description: 'Optional case-insensitive substring to filter IDs. Pass empty string to list all (capped at 200).',
+                    },
+                },
+                required: [],
+            },
+        },
+    },
+    {
+        type: 'function',
+        function: {
+            name: 'get_shedb_doc',
+            description: 'Retrieve a specific document from the sheDB document store by its ID. ' + 'Use list_shedb_docs first to discover valid IDs.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    id: {
+                        type: 'string',
+                        description: 'The exact document ID to retrieve.',
+                    },
+                },
+                required: ['id'],
+            },
+        },
+    },
+    {
+        type: 'function',
+        function: {
+            name: 'list_matter_devices',
+            description:
+                'List all paired Matter devices with their online status, endpoints and available clusters. ' +
+                'Use this whenever the user asks about a Matter device or smart home hardware. ' +
+                'Use node and endpoint friendly names in matter commands.',
+            parameters: {
+                type: 'object',
+                properties: {},
+                required: [],
+            },
+        },
+    },
 ];
 
 /** Same definitions in Anthropic tool format. */
@@ -125,11 +189,24 @@ const TOOL_DEFINITIONS_ANTHROPIC = TOOL_DEFINITIONS.map((t) => ({
 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}`;
+            case 'search_mqtt_topics':
+                return toolSearchMqttTopics(args, ctx.store);
+            case 'get_mqtt_topic':
+                return toolGetMqttTopic(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);
+            case 'list_shedb_docs':
+                return toolListShedbDocs(args);
+            case 'get_shedb_doc':
+                return toolGetShedbDoc(args);
+            case 'list_matter_devices':
+                return toolListMatterDevices();
+            default:
+                return `Unknown tool: ${name}`;
         }
     } catch (e) {
         return `Tool error (${name}): ${e.message}`;
@@ -202,9 +279,79 @@ async function toolSheFetch({ 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 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}`;
 }
 
+function toolGetMqttTopic({ topic }, store) {
+    if (!store) return 'MQTT state store not available.';
+    if (!topic || typeof topic !== 'string') return 'topic argument is required.';
+    const obj = store.getObject('mqtt::' + topic);
+    if (!obj) return `Topic "${topic}" not found in state store. Use search_mqtt_topics to discover topics.`;
+    const ts = new Date(obj.ts).toISOString();
+    const lc = new Date(obj.lc ?? obj.ts).toISOString();
+    return `${topic}: ${JSON.stringify(obj.val)}\n  last updated: ${ts}\n  last changed: ${lc}`;
+}
+
+function toolListShedbDocs({ filter = '' }) {
+    try {
+        const core = require('./shedb').getCore();
+        if (!core) return 'sheDB not initialised.';
+        const ids = Object.keys(core.docs).sort();
+        const q = String(filter).toLowerCase();
+        const filtered = q ? ids.filter((id) => id.toLowerCase().includes(q)) : ids;
+        if (filtered.length === 0) return q ? `No documents found matching "${filter}".` : 'No documents in sheDB.';
+        const shown = filtered.slice(0, 200);
+        const suffix = filtered.length > 200 ? ` (capped at 200 of ${filtered.length} total)` : '';
+        return `${shown.length} document(s)${suffix}:\n${shown.join('\n')}`;
+    } catch (e) {
+        return `sheDB not available: ${e.message}`;
+    }
+}
+
+function toolGetShedbDoc({ id }) {
+    if (!id || typeof id !== 'string') return 'id argument is required.';
+    try {
+        const core = require('./shedb').getCore();
+        if (!core) return 'sheDB not initialised.';
+        const doc = core.docs[id];
+        if (doc === undefined) return `Document "${id}" not found. Use list_shedb_docs to see available IDs.`;
+        return `## ${id}\n${JSON.stringify(doc, null, 2)}`;
+    } catch (e) {
+        return `sheDB not available: ${e.message}`;
+    }
+}
+
+function toolListMatterDevices() {
+    try {
+        const controller = require('../matter/controller');
+        if (typeof controller.listPaired !== 'function') return 'Matter controller not available.';
+        const nodes = controller.listPaired();
+        if (nodes.length === 0) return 'No Matter devices paired.';
+        const lines = [`${nodes.length} paired Matter device(s):`];
+        for (const n of nodes) {
+            lines.push(`\n### ${n.name || 'Unnamed'} (nodeId: "${n.nodeId}", ${n.online ? 'online' : 'offline'})`);
+            try {
+                const endpoints = controller.getEndpoints(n.nodeId);
+                for (const ep of endpoints) {
+                    if (ep.endpointId === 0) continue; // skip root endpoint
+                    const name = ep.name || String(ep.endpointId);
+                    lines.push(`- endpoint "${name}" (id: ${ep.endpointId}): ${ep.clusters.join(', ')}`);
+                }
+            } catch {
+                /* node may be offline */
+            }
+        }
+        return lines.join('\n');
+    } catch (e) {
+        return `Matter controller not available: ${e.message}`;
+    }
+}
+
 module.exports = { TOOL_DEFINITIONS, TOOL_DEFINITIONS_ANTHROPIC, executeTool };

package/src/web/deps-api.js

@@ -56,7 +56,33 @@ function isValidVersion(v) {
 router.get('/', (req, res) => {
     const pkg = readPackageJson();
     const deps = pkg.dependencies || {};
-    res.json(Object.entries(deps).map(([name, version]) => ({ name, version })));
+    res.json(
+        Object.entries(deps).map(([name, version]) => {
+            let url = `https://www.npmjs.com/package/${encodeURIComponent(name)}`;
+            try {
+                const meta = JSON.parse(fs.readFileSync(path.join(STORAGE_ROOT, 'node_modules', name, 'package.json'), 'utf8'));
+                if (meta.homepage && /^https?:\/\//.test(meta.homepage)) {
+                    url = meta.homepage;
+                } else {
+                    let repo = typeof meta.repository === 'object' ? meta.repository.url : meta.repository;
+                    if (typeof repo === 'string' && repo) {
+                        repo = repo
+                            .replace(/^git\+/, '')
+                            .replace(/\.git$/, '')
+                            .replace(/^git:\/\//, 'https://');
+                        if (/^https?:\/\//.test(repo)) url = repo;
+                        else {
+                            const m = repo.match(/^(?:github:|github\.com[:/])?([\w.-]+\/[\w.-]+)$/);
+                            if (m) url = `https://github.com/${m[1]}`;
+                        }
+                    }
+                }
+            } catch {
+                /* not installed or no metadata */
+            }
+            return { name, version, url };
+        }),
+    );
 });
 
 // GET /she/deps/search?q=term  — search the npm registry
@@ -77,6 +103,11 @@ router.get('/search', (req, res) => {
                     name: obj.package.name,
                     version: obj.package.version,
                     description: obj.package.description ?? '',
+                    url:
+                        obj.package.links?.repository ||
+                        obj.package.links?.homepage ||
+                        obj.package.links?.npm ||
+                        `https://www.npmjs.com/package/${encodeURIComponent(obj.package.name)}`,
                 }));
                 res.json(results);
             } catch {

package/src/web/matter-api.js

@@ -66,8 +66,8 @@ router.get('/devices/:nodeId', (req, res) => {
         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 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) {

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

@@ -16,3 +16,10 @@ Use a short kebab-case filename. Do NOT put the hint outside or before the code
 ### 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.
+
+### Tool usage
+When the user asks about a specific MQTT topic, its current value or state — use `search_mqtt_topics` to discover topics or `get_mqtt_topic` for a direct lookup. Never invent topic names.
+When the user asks about a Matter device or smart home hardware — call `list_matter_devices` to retrieve the actual device list, endpoints and clusters.
+When the user asks about a sheDB document — call `list_shedb_docs` to find the ID, then `get_shedb_doc` to read it.
+Always look up real data before writing scripts that reference specific topics, documents or devices.
+If `search_mqtt_topics` returns several plausible matches and it is unclear which one the user means, ask the user to confirm the correct topic before writing the script — never guess.

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

@@ -53,6 +53,9 @@ she.db.query(filter, mapFn, [reduceFn])  Synchronous ad-hoc query → Array
 ```
 
 ### Matter
+
+Use names for nodeId, endpointId and cluster, not numbers
+
 ```
 she.matter.sub(nodeId, endpointId, cluster, attr, cb)    Subscribe to attribute
 she.matter.unsub(listenerId)
@@ -70,4 +73,18 @@ 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
+she.fetch(url, [opts])               HTTP/HTTPS fetch → Promise<string|object>
+                                       Auto-parses JSON by Content-Type.
+                                       Throws on non-2xx status.
+```
+
+### Script HTTP API
+Scripts can expose HTTP endpoints under `/api/<scriptName>/`.
+```
+she.api.get(path, handler)           GET /api/<script><path> → handler(req)
+she.api.post(path, handler)          POST /api/<script><path> → handler(req, body)
+she.api.put(path, handler)           PUT /api/<script><path> → handler(req, body)
+she.api.delete(path, handler)        DELETE /api/<script><path> → handler(req)
 ```
+req = { params, query, headers }. Return value (or resolved Promise) is JSON-serialised.
+Express path params supported: she.api.get('/items/:id', (req) => ...).

package/src/web/scripts-api.js

@@ -171,7 +171,6 @@ router.use((req, res) => {
         }
         const absNew = safePath(root, newName);
         if (!absNew) return res.status(400).json({ error: 'Invalid newPath' });
-        if (!absNew.endsWith('.js')) return res.status(400).json({ error: 'Only .js files are allowed' });
         try {
             fs.mkdirSync(path.dirname(absNew), { recursive: true });
             fs.renameSync(abs, absNew);

package/src/web/server.js

@@ -60,7 +60,9 @@ app.post('/she/restart', (req, res) => {
 
 // Runtime stats — script count + MQTT topic count
 let _getStats = null;
-function setStatsProvider(fn) { _getStats = fn; }
+function setStatsProvider(fn) {
+    _getStats = fn;
+}
 app.get('/she/status', (req, res) => {
     res.json(_getStats ? _getStats() : { scripts: 0, topics: 0 });
 });

package/src/web/shedb-api.js

@@ -121,7 +121,7 @@ router.use('/views', (req, res) => {
             map,
             reduce: reduce || undefined,
             ...(mqttpub ? { mqttpub: true } : {}),
-            ...(retain   ? { retain:   true } : {}),
+            ...(retain ? { retain: true } : {}),
         };
         core.query(id, payload);
         return res.json({ ok: true });

package/src/web/shedb.js

@@ -40,7 +40,7 @@ function init({ dbPath, dbPublish, dbRetain, dbPrefix, mqttName, mqtt, log, broa
     _mqttName = mqttName;
     _dbPublish = dbPublish;
     _dbRetain = dbRetain;
-    _dbPrefix = (dbPrefix && dbPrefix.endsWith('/')) ? dbPrefix : (dbPrefix || 'she/db/') + '/';
+    _dbPrefix = dbPrefix && dbPrefix.endsWith('/') ? dbPrefix : (dbPrefix || 'she/db/') + '/';
     _broadcast = broadcast;
 
     _core = new SheDBCore({ dbPath, log });
@@ -78,11 +78,7 @@ function init({ dbPath, dbPublish, dbRetain, dbPrefix, mqttName, mqtt, log, broa
         // Per-view MQTT publish (independent of global dbPublish setting)
         const query = _core.queries[id];
         if (query && query.mqttpub && _mqtt && view && !view.error) {
-            _mqtt.publish(
-                _dbPrefix + 'view/' + id,
-                JSON.stringify(view.result ?? []),
-                { retain: query.retain === true }
-            );
+            _mqtt.publish(_dbPrefix + 'view/' + id, JSON.stringify(view.result ?? []), { retain: query.retain === true });
         }
     });