smart-home-engine 1.53.4 → 2.0.0

package/src/matter/thread.js

@@ -0,0 +1,267 @@
+'use strict';
+
+/**
+ * Thread networks and border routers (roadmap M15): what matter.js's `@matter/thread-br-client`
+ * sees on the LAN — every `_meshcop._udp` border agent (Apple TV, HomePod, OTBRs, our ESP router)
+ * with its network name, extended PAN ID, vendor and model, Thread version, state bitmap and
+ * addresses — grouped by network, plus a probe of the classic OpenThread REST API (OTBR on 8081,
+ * esp-thread-br on 80) per border router so a manageable one shows its role, RLOC16 and leader data.
+ *
+ * Read-only: nothing is written to any border router here.
+ *
+ * Reuse per D-14: the registry, the REST probe and client are the library's (Apache-2.0, used as a
+ * dependency, nothing copied).
+ */
+
+let _log = null;
+let _broadcast = null;
+let _registry = null;
+let _env = null;
+/** extAddressHex → { capability, node, probedAt, error, port } */
+const _probes = new Map();
+const PROBE_TTL_MS = 10 * 60 * 1000;
+const PROBE_PORTS = [8081, 80];
+
+// ── The border agent state bitmap (Thread MeshCoP, `_meshcop` TXT "sb", 4 bytes big-endian) ──
+
+const CONNECTION_MODES = ['not allowed', 'PSKc', 'PSKd', 'vendor', 'X.509'];
+const IF_STATUS = ['not initialised', 'initialised, not active', 'active'];
+const AVAILABILITY = ['infrequent', 'high'];
+const ROLES = ['disabled or detached', 'child', 'router', 'leader'];
+
+/**
+ * Decode the state bitmap: connection mode (bits 0–2), Thread interface status (3–4),
+ * availability (5–6), BBR active (7), BBR primary (8), Thread role (9–10), ePSKc supported (11).
+ * @param {string|undefined} hex
+ */
+function decodeStateBitmap(hex) {
+    if (!hex || !/^[0-9a-fA-F]{1,8}$/.test(hex)) return null;
+    const v = parseInt(hex, 16);
+    return {
+        connectionMode: CONNECTION_MODES[v & 0x7] ?? `mode ${v & 0x7}`,
+        interfaceStatus: IF_STATUS[(v >> 3) & 0x3] ?? `status ${(v >> 3) & 0x3}`,
+        availability: AVAILABILITY[(v >> 5) & 0x3] ?? `availability ${(v >> 5) & 0x3}`,
+        bbrActive: !!(v & (1 << 7)),
+        bbrPrimary: !!(v & (1 << 8)),
+        role: ROLES[(v >> 9) & 0x3] ?? `role ${(v >> 9) & 0x3}`,
+        epskcSupported: !!(v & (1 << 11)),
+        threadActive: ((v >> 3) & 0x3) === 2,
+    };
+}
+
+function _entryView(e) {
+    const probe = _probes.get(e.extAddressHex) ?? null;
+    return {
+        extAddress: e.extAddressHex,
+        extPanId: e.extendedPanIdHex ?? null,
+        networkName: e.networkName ?? null,
+        vendorName: e.vendorName ?? null,
+        modelName: e.modelName ?? null,
+        hostname: e.hostname ?? null,
+        addresses: e.addresses ?? [],
+        meshcopPort: e.meshcopPort ?? null,
+        trelPort: e.trelPort ?? null,
+        threadVersion: e.threadVersion ?? null,
+        swVersion: e.swVersion ?? null,
+        borderAgentId: e.borderAgentIdHex ?? null,
+        partitionId: e.partitionIdHex ?? null,
+        activeTimestamp: e.activeTimestampHex ?? null,
+        domainName: e.domainName ?? null,
+        state: decodeStateBitmap(e.stateBitmapHex),
+        sources: e.sources ?? [],
+        lastSeen: e.lastSeen ?? null,
+        rest: probe
+            ? {
+                  manageable: !!probe.capability,
+                  port: probe.port ?? null,
+                  baseUrl: probe.capability?.baseUrl ?? null,
+                  diagnosticsApi: probe.capability?.diagnosticsApi ?? null,
+                  node: probe.node ?? null,
+                  probedAt: probe.probedAt,
+                  error: probe.error ?? null,
+              }
+            : null,
+    };
+}
+
+/**
+ * The networks on the LAN, grouped by extended PAN ID, each with its border routers; border
+ * routers that name no PAN ID go into `unknown`.
+ * @param {object[]} [entries]  the registry's entries (for tests)
+ */
+function listNetworks(entries) {
+    const list = entries ?? (_registry ? _registry.list() : []);
+    const byPan = new Map();
+    const unknown = [];
+    for (const e of list) {
+        const view = _entryView(e);
+        if (!view.extPanId) {
+            unknown.push(view);
+            continue;
+        }
+        let net = byPan.get(view.extPanId);
+        if (!net) {
+            net = { extPanId: view.extPanId, networkName: view.networkName, borderRouters: [], partitions: new Set(), datasetKnown: _datasetKnown(view.extPanId) };
+            byPan.set(view.extPanId, net);
+        }
+        if (!net.networkName && view.networkName) net.networkName = view.networkName;
+        if (view.partitionId) net.partitions.add(view.partitionId);
+        net.borderRouters.push(view);
+    }
+    const networks = [...byPan.values()].map((n) => ({
+        ...n,
+        partitions: [...n.partitions],
+        routerCount: n.borderRouters.length,
+        borderRouters: n.borderRouters.sort((a, b) => (a.vendorName ?? '').localeCompare(b.vendorName ?? '') || a.extAddress.localeCompare(b.extAddress)),
+    }));
+    networks.sort((a, b) => (a.networkName ?? '').localeCompare(b.networkName ?? ''));
+    return { running: !!_registry, networks, unknown };
+}
+
+function _datasetKnown(extPanId) {
+    try {
+        return require('./thread-datasets').has(extPanId);
+    } catch {
+        return false;
+    }
+}
+
+/** Import the active dataset from a border router with the REST API (M17). */
+async function importDataset(extAddressHex) {
+    const e = _registry?.get(extAddressHex);
+    if (!e) throw new Error(`border router not found: ${extAddressHex}`);
+    const probe = _probes.get(extAddressHex);
+    if (!probe?.capability) throw new Error('the border router has no REST API (probe it first)');
+    const { OtbrRestClient } = require('@matter/thread-br-client');
+    const client = new OtbrRestClient({ host: _ipForProbe(e), port: probe.port });
+    const ds = await client.getDataset();
+    if (!ds?.activeHex) throw new Error('the border router returned no active dataset');
+    return require('./thread-datasets').add({ tlv: ds.activeHex, source: 'router', note: `${e.vendorName ?? ''} ${e.modelName ?? ''}`.trim() });
+}
+
+function _ipForProbe(e) {
+    // prefer IPv4, then a global IPv6, then anything (a link-local needs a scope we do not have)
+    const addrs = e.addresses ?? [];
+    return addrs.find((a) => /^\d+\.\d+\.\d+\.\d+$/.test(a)) ?? addrs.find((a) => a.includes(':') && !/^fe80:/i.test(a)) ?? addrs[0] ?? null;
+}
+
+/**
+ * Probe a border router's classic REST API (OTBR: 8081, esp-thread-br: 80) and, when found, read
+ * its node info. Cached for ten minutes; `force` probes again.
+ */
+async function probeRouter(extAddressHex, { force = false } = {}) {
+    const e = _registry?.get(extAddressHex);
+    if (!e) throw new Error(`border router not found: ${extAddressHex}`);
+    const cached = _probes.get(extAddressHex);
+    if (cached && !force && Date.now() - cached.probedAt < PROBE_TTL_MS) return _entryView(e);
+    const { OtbrRestProbe, OtbrRestClient } = require('@matter/thread-br-client');
+    const host = _ipForProbe(e);
+    const result = { capability: null, node: null, probedAt: Date.now(), error: null, port: null };
+    if (!host) {
+        result.error = 'no address';
+    } else {
+        for (const port of PROBE_PORTS) {
+            try {
+                const cap = await OtbrRestProbe.probe(host, port, 1500);
+                if (!cap) continue;
+                result.capability = cap;
+                result.port = port;
+                try {
+                    const client = new OtbrRestClient({ host, port });
+                    const node = await client.getNode();
+                    result.node = {
+                        state: node.state ?? null,
+                        role: node.state ?? null,
+                        rloc16: node.rloc16 === undefined ? null : Number(node.rloc16),
+                        rlocAddress: node.rlocAddress ?? null,
+                        numOfRouter: node.numOfRouter ?? null,
+                        networkName: node.networkName ?? null,
+                        extAddress: node.extAddress ? Buffer.from(node.extAddress).toString('hex').toUpperCase() : null,
+                        extPanId: node.extPanId ? Buffer.from(node.extPanId).toString('hex').toUpperCase() : null,
+                        leaderData: node.leaderData ?? null,
+                    };
+                } catch (err) {
+                    result.error = `node info: ${err.message}`;
+                }
+                break;
+            } catch (err) {
+                result.error = err.message;
+            }
+        }
+    }
+    _probes.set(extAddressHex, result);
+    _log?.debug(
+        `matter thread: ${e.vendorName ?? ''} ${e.modelName ?? ''} ${extAddressHex} REST ${result.capability ? 'found on ' + result.port : 'not found'}${result.error ? ' (' + result.error + ')' : ''}`,
+    );
+    _broadcast?.({ type: 'matter:thread' });
+    return _entryView(e);
+}
+
+let _probeQueue = Promise.resolve();
+function _scheduleProbe(e) {
+    _probeQueue = _probeQueue.then(() => probeRouter(e.extAddressHex).catch(() => {}));
+}
+
+/**
+ * Start the passive mDNS discovery on the controller's environment.
+ * @param {object} env  the matter.js Environment (shares the controller's mDNS)
+ */
+async function start(env, { log, broadcast } = {}) {
+    _log = log ?? _log;
+    _broadcast = broadcast ?? _broadcast;
+    _env = env;
+    if (_registry) return;
+    const { BorderRouterRegistry } = require('@matter/thread-br-client');
+    const registry = new BorderRouterRegistry(env);
+    registry.events.added.on((e) => {
+        _log?.info(`matter thread: border router ${e.vendorName ?? '?'} ${e.modelName ?? ''} (${e.networkName ?? 'network ?'}, ${e.extAddressHex})`);
+        _broadcast?.({ type: 'matter:thread' });
+        _scheduleProbe(e);
+    });
+    registry.events.updated.on(() => _broadcast?.({ type: 'matter:thread' }));
+    registry.events.removed.on((e) => {
+        _probes.delete(e.extAddressHex);
+        _log?.info(`matter thread: border router ${e.extAddressHex} gone`);
+        _broadcast?.({ type: 'matter:thread' });
+    });
+    await registry.start();
+    _registry = registry;
+    _log?.info('matter thread: border router discovery started');
+}
+
+async function stop() {
+    const r = _registry;
+    _registry = null;
+    _probes.clear();
+    if (r) {
+        try {
+            await r.stop();
+        } catch {
+            /* stopping */
+        }
+    }
+}
+
+/** Probe every border router again (the refresh button). */
+async function refresh() {
+    if (!_registry) throw new Error('Thread discovery is not running');
+    for (const e of _registry.list()) await probeRouter(e.extAddressHex, { force: true }).catch(() => {});
+    return listNetworks();
+}
+
+function isRunning() {
+    return !!_registry;
+}
+
+/** The library's own entry (for `connectMeshcop`). */
+function _registryEntry(extAddressHex) {
+    return _registry?.get(extAddressHex) ?? null;
+}
+
+/** Test hook. */
+function _inject({ registry } = {}) {
+    _registry = registry ?? null;
+    _probes.clear();
+}
+
+module.exports = { start, stop, refresh, listNetworks, probeRouter, importDataset, decodeStateBitmap, isRunning, _inject, _probes, _registryEntry, _env: () => _env };

package/src/web/ai-tools.js

@@ -239,6 +239,85 @@ const TOOL_DEFINITIONS = [
             },
         },
     },
+    {
+        type: 'function',
+        function: {
+            name: 'get_matter_device',
+            description:
+                'One Matter device in full: every endpoint with its clusters and attribute values (what list_matter_devices leaves out), the device types, the CSA ledger vendor/product. Narrow with cluster.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    node: { type: 'string', description: 'Node id or device name.' },
+                    endpoint: { type: 'string', description: 'Only this endpoint (id or name).' },
+                    cluster: { type: 'string', description: 'Only this cluster (camelCase, e.g. "onOff"); then every attribute of it is listed.' },
+                },
+                required: ['node'],
+            },
+        },
+    },
+    {
+        type: 'function',
+        function: {
+            name: 'list_matter_bindings',
+            description:
+                'The Matter bindings (a switch controlling a device directly, without she): per source endpoint its targets and clusters, whether she or another controller made it; and which endpoints can be binding sources or targets.',
+            parameters: { type: 'object', properties: { node: { type: 'string', description: 'Only bindings of this source or target node (id or name).' } }, required: [] },
+        },
+    },
+    {
+        type: 'function',
+        function: {
+            name: 'list_matter_groups',
+            description: "she's Matter groups (one multicast command for several devices): members with their state and provisioning status, the derived group state, the key set.",
+            parameters: { type: 'object', properties: {}, required: [] },
+        },
+    },
+    {
+        type: 'function',
+        function: {
+            name: 'get_matter_fabrics',
+            description: 'Which controllers (fabrics — Apple Home, Home Assistant, she, …) a Matter device belongs to, and whether a pairing window is open.',
+            parameters: { type: 'object', properties: { node: { type: 'string', description: 'Node id or device name.' } }, required: ['node'] },
+        },
+    },
+    {
+        type: 'function',
+        function: {
+            name: 'get_thread_networks',
+            description:
+                'The Thread networks on the LAN with their border routers (Apple TV, HomePod, OpenThread, the ESP router): vendor, model, Thread version, role, state, addresses, last seen; whether she knows the network credentials.',
+            parameters: { type: 'object', properties: {}, required: [] },
+        },
+    },
+    {
+        type: 'function',
+        function: {
+            name: 'get_thread_mesh',
+            description:
+                'The Thread mesh: every Thread device in she\'s fabric with its routing role, RLOC16 and partition, its neighbours with link quality (LQI 3 good, 2 fair, 1 poor) and RSSI, the border routers, Wi-Fi devices by RSSI, bindings. For "why is X offline", "which devices route over Y", "where is the weak link".',
+            parameters: {
+                type: 'object',
+                properties: {
+                    node: { type: 'string', description: 'Only this device and its links (id or name).' },
+                    refresh: {
+                        type: 'boolean',
+                        description: 'Re-read the neighbour tables from the devices first (slow — sleepy devices answer late). Default false: the last read.',
+                    },
+                },
+                required: [],
+            },
+        },
+    },
+    {
+        type: 'function',
+        function: {
+            name: 'get_matter_health',
+            description:
+                'The health of the Matter devices and the Thread mesh: battery, last seen, offline periods, active alerts (low battery, offline, leader change, partition, border router offline, degraded link), firmware updates the ledger offers.',
+            parameters: { type: 'object', properties: { node: { type: 'string', description: 'Only this device (id or name).' } }, required: [] },
+        },
+    },
     {
         type: 'function',
         function: {
@@ -557,6 +636,20 @@ async function runTool(name, args, ctx) {
                 return await toolListMatterDevices(args);
             case 'get_matter_attribute':
                 return await toolGetMatterAttribute(args);
+            case 'get_matter_device':
+                return await toolGetMatterDevice(args);
+            case 'list_matter_bindings':
+                return await toolListMatterBindings(args);
+            case 'list_matter_groups':
+                return toolListMatterGroups(args);
+            case 'get_matter_fabrics':
+                return await toolGetMatterFabrics(args);
+            case 'get_thread_networks':
+                return toolGetThreadNetworks(args);
+            case 'get_thread_mesh':
+                return await toolGetThreadMesh(args);
+            case 'get_matter_health':
+                return await toolGetMatterHealth(args);
             case 'get_topic_history':
                 return await toolGetTopicHistory(args, ctx);
             case 'get_timeline':
@@ -1758,6 +1851,282 @@ async function toolGetMatterAttribute({ node, endpoint, cluster, attribute } = {
     }
 }
 
+// ── Matter and Thread (I44) — read-only views over the controller's modules ──
+
+function matterModule(name) {
+    try {
+        return require(`../matter/${name}`);
+    } catch {
+        return null;
+    }
+}
+
+function resolveNodeId(controller, node) {
+    const s = String(node);
+    const paired = controller.listPaired();
+    const hit = paired.find((n) => n.nodeId === s) ?? paired.find((n) => n.name === s) ?? paired.find((n) => (n.name ?? '').toLowerCase() === s.toLowerCase());
+    return hit ? hit.nodeId : null;
+}
+
+const fmtJson = (v) => {
+    const j = JSON.stringify(v);
+    return j.length > 160 ? j.slice(0, 157) + '…' : j;
+};
+
+async function toolGetMatterDevice({ node, endpoint, cluster } = {}) {
+    const controller = matterController();
+    if (!controller) return 'Matter controller not available.';
+    if (!node) return 'node is required.';
+    const nodeId = resolveNodeId(controller, node);
+    if (!nodeId) return `No Matter device "${node}".`;
+    const dev = controller.listPaired().find((n) => n.nodeId === nodeId);
+    let endpoints;
+    try {
+        endpoints = controller.getEndpoints(nodeId);
+    } catch (e) {
+        return `Cannot read ${node}: ${e.message}`;
+    }
+    const lines = [`### ${dev.name || 'Unnamed'} (nodeId "${nodeId}", ${dev.online ? 'online' : 'offline'})`];
+    const dcl = matterModule('dcl');
+    if (dcl && typeof controller.getDeviceInfo === 'function') {
+        try {
+            const info = await withTimeout(controller.getDeviceInfo(nodeId), 3000);
+            if (info.vendorName || info.product)
+                lines.push(
+                    `ledger: ${info.vendorName ?? '?'}${info.product?.productName ? ' · ' + info.product.productName : ''}${info.reported?.softwareVersionString ? ' · firmware ' + info.reported.softwareVersionString : ''}`,
+                );
+        } catch {
+            /* optional */
+        }
+    }
+    const wantEp = endpoint === undefined || endpoint === null || endpoint === '' ? null : String(endpoint);
+    const perCluster = cluster ? 1000 : 12;
+    for (const ep of endpoints) {
+        if (wantEp !== null && String(ep.endpointId) !== wantEp && (ep.name ?? '') !== wantEp) continue;
+        const types = (ep.clusters.find((c) => c.name === 'descriptor')?.attrs?.deviceTypeList ?? []).map((t) => `0x${Number(t?.deviceType ?? t).toString(16)}`);
+        lines.push(`\n- endpoint ${ep.endpointId}${ep.name ? ` "${ep.name}"` : ''}${types.length ? ` (device types ${types.join(', ')})` : ''}`);
+        for (const c of ep.clusters) {
+            if (cluster && c.name.toLowerCase() !== String(cluster).toLowerCase()) continue;
+            const entries = Object.entries(c.attrs ?? {}).filter(
+                ([k]) => !['generatedCommandList', 'acceptedCommandList', 'eventList', 'attributeList', 'clusterRevision', 'featureMap'].includes(k),
+            );
+            const shown = entries.slice(0, perCluster).map(([k, v]) => `${k}=${fmtJson(v)}`);
+            lines.push(`  - ${c.name}: ${shown.join(', ')}${entries.length > perCluster ? ` … ${entries.length - perCluster} more (ask with cluster="${c.name}")` : ''}`);
+        }
+    }
+    return lines.join('\n');
+}
+
+async function toolListMatterBindings({ node } = {}) {
+    const controller = matterController();
+    if (!controller || typeof controller.listBindings !== 'function') return 'Matter controller not available.';
+    const want = node ? resolveNodeId(controller, node) : null;
+    if (node && !want) return `No Matter device "${node}".`;
+    let bindings;
+    try {
+        bindings = await withTimeout(controller.listBindings(), 8000);
+    } catch (e) {
+        return `Cannot read the bindings: ${e.message}`;
+    }
+    const rows = bindings.filter((b) => !want || b.sourceNodeId === want || b.node === want);
+    const lines = [];
+    if (rows.length === 0) lines.push(want ? `No bindings involve ${node}.` : 'No bindings on any paired device.');
+    else {
+        lines.push(`${rows.length} binding entr${rows.length === 1 ? 'y' : 'ies'}:`);
+        for (const b of rows) {
+            const src = `${b.sourceName ?? 'node ' + b.sourceNodeId}/${b.sourceEndpointName ?? 'ep ' + b.sourceEndpointId}`;
+            const tgt =
+                b.group !== null && b.group !== undefined
+                    ? (b.targetName ?? `group ${b.group}`)
+                    : b.own
+                      ? `${b.targetName ?? 'node ' + b.node}/${b.targetEndpointName ?? 'ep ' + b.endpoint}`
+                      : `node ${b.node} ep ${b.endpoint} (that fabric's numbering)`;
+            lines.push(`- ${src} → ${tgt}: ${b.clusterName ?? 'cluster ' + b.cluster} [${b.own ? 'she' : 'another controller, fabric ' + b.fabricIndex}]`);
+        }
+    }
+    if (typeof controller.bindingCandidates === 'function') {
+        try {
+            const c = controller.bindingCandidates();
+            const name = (e) => `${e.nodeName ?? 'node ' + e.nodeId}/${e.name ?? 'ep ' + e.endpointId}`;
+            lines.push(
+                `\nCan be a source (Binding cluster + client cluster): ${c.sources.length ? c.sources.map((e) => `${name(e)} (${e.clusters.map((x) => x.label).join(', ')})`).join('; ') : 'none'}`,
+            );
+            lines.push(`Can be a target: ${c.targets.length ? c.targets.map((e) => `${name(e)} (${e.clusters.map((x) => x.label).join(', ')})`).join('; ') : 'none'}`);
+            if (c.notBindable.length) lines.push(`Cannot bind (button events only — use she.matter.sub): ${c.notBindable.map(name).join('; ')}`);
+        } catch {
+            /* optional */
+        }
+    }
+    return lines.join('\n');
+}
+
+function toolListMatterGroups() {
+    const controller = matterController();
+    if (!controller || typeof controller.listGroups !== 'function') return 'Matter controller not available.';
+    const g = controller.listGroups();
+    if (!g.available) return `Groups are not available${g.error ? ': ' + g.error : ''}.`;
+    if (!g.groups.length) return 'No Matter groups defined.';
+    const lines = [`${g.groups.length} group(s):`];
+    for (const x of g.groups) {
+        const st = x.state.on === null ? 'state unknown' : x.state.on === 'all' ? 'all on' : x.state.on === 'some' ? `${x.state.onCount} of ${x.state.memberCount} on` : 'all off';
+        lines.push(
+            `\n### ${x.name} (group id ${x.id}, key set ${x.keySet?.shared ? 'shared' : 'own'}; ${st}${x.state.level !== null ? `, level ${x.state.level}` : ''}) — she.matter.send('group:${x.name}', null, 'onOff', 'on')`,
+        );
+        for (const m of x.members)
+            lines.push(
+                `- ${m.name ?? 'node ' + m.nodeId}/${m.endpointName ?? 'ep ' + m.endpointId}: ${m.clusterNames.join(', ')}; ${m.online ? 'online' : 'offline'}; ${m.status}${m.error ? ' (' + m.error + ')' : ''}${m.state.onOff !== null ? '; ' + (m.state.onOff ? 'on' : 'off') : ''}${m.state.level !== null ? ', level ' + m.state.level : ''}`,
+            );
+    }
+    return lines.join('\n');
+}
+
+async function toolGetMatterFabrics({ node } = {}) {
+    const controller = matterController();
+    if (!controller || typeof controller.listFabrics !== 'function') return 'Matter controller not available.';
+    if (!node) return 'node is required.';
+    const nodeId = resolveNodeId(controller, node);
+    if (!nodeId) return `No Matter device "${node}".`;
+    try {
+        const f = await withTimeout(controller.listFabrics(nodeId), 8000);
+        const lines = [
+            `${node}: ${f.fabrics.length} fabric(s)${f.supportedFabrics ? ` of ${f.supportedFabrics} supported` : ''}${f.fresh ? '' : ' (from the cache — the device is offline)'}:`,
+        ];
+        for (const x of f.fabrics)
+            lines.push(`- ${x.name}${x.vendorName ? ` (${x.vendorName})` : ''}${x.own ? ' — she' : ''}: fabric index ${x.fabricIndex}, node id there ${x.nodeId}`);
+        const w = f.window;
+        lines.push(
+            w.status
+                ? `A pairing window is open${w.codes ? ` (she opened it; manual code ${w.codes.manualCode}, closes ${isoShort(w.codes.expiresAt)})` : ''}.`
+                : 'No pairing window open.',
+        );
+        return lines.join('\n');
+    } catch (e) {
+        return `Cannot read the fabrics of ${node}: ${e.message}`;
+    }
+}
+
+function toolGetThreadNetworks() {
+    const thread = matterModule('thread');
+    if (!thread) return 'Thread discovery not available.';
+    const n = thread.listNetworks();
+    if (!n.running) return 'Thread discovery is not running (the Matter controller is off).';
+    if (!n.networks.length && !n.unknown.length) return 'No Thread border router has announced itself on the LAN (discovery is passive — give it a minute after start).';
+    const lines = [`${n.networks.length} Thread network(s):`];
+    for (const net of n.networks) {
+        lines.push(
+            `\n### ${net.networkName ?? 'unnamed'} (ext PAN ID ${net.extPanId}; credentials ${net.datasetKnown ? 'known to she' : 'unknown'}${net.partitions.length > 1 ? `; WARNING ${net.partitions.length} partition IDs — split network` : ''})`,
+        );
+        for (const br of net.borderRouters) {
+            const st = br.state ? `${br.state.role}${br.state.bbrPrimary ? ', primary BBR' : ''}, ${br.state.interfaceStatus}` : 'state unknown';
+            lines.push(
+                `- ${br.vendorName ?? '?'} ${br.modelName ?? ''}${br.hostname ? ` (${br.hostname.replace(/\.$/, '')})` : ''}: Thread ${br.threadVersion ?? '?'}; ${st}; ${br.addresses.slice(0, 2).join(', ')}; seen ${br.lastSeen ? ago(Date.now() - br.lastSeen) + ' ago' : '?'}${br.rest?.manageable ? `; REST API on :${br.rest.port}${br.rest.node ? ` (${br.rest.node.role}, ${br.rest.node.numOfRouter ?? '?'} routers)` : ''}` : ''}`,
+            );
+        }
+    }
+    if (n.unknown.length) lines.push(`\nBorder routers without a network: ${n.unknown.map((b) => `${b.vendorName ?? '?'} ${b.modelName ?? ''}`).join('; ')}`);
+    return lines.join('\n');
+}
+
+async function toolGetThreadMesh({ node, refresh = false } = {}) {
+    const mesh = matterModule('thread-mesh');
+    const controller = matterController();
+    if (!mesh || !controller) return 'Thread mesh not available.';
+    let g;
+    try {
+        g = refresh ? await withTimeout(mesh.refresh(), 60000) : await withTimeout(mesh.getMesh(), 10000);
+    } catch (e) {
+        return `Cannot read the mesh: ${e.message}`;
+    }
+    const want = node ? resolveNodeId(controller, node) : null;
+    if (node && !want) return `No Matter device "${node}".`;
+    const nameOf = (id) => g.nodes.find((x) => x.id === id)?.name ?? id;
+    const nodes = g.nodes
+        .filter((n) => n.kind !== 'other')
+        .filter((n) => !want || n.nodeId === want || g.links.some((l) => (l.source === `node:${want}` && l.target === n.id) || (l.target === `node:${want}` && l.source === n.id)));
+    if (!nodes.length) return want ? `${node} has no Thread or Wi-Fi diagnostics.` : "No Thread device in she's fabric and no border router seen.";
+    const lines = [
+        `${g.nodes.filter((n) => n.kind === 'thread').length} Thread device(s) in she's fabric, ${g.nodes.filter((n) => n.kind === 'border-router').length} border router(s), ${g.links.filter((l) => l.kind === 'neighbour').length} link(s)${g.lastRefresh ? `; tables read ${ago(Date.now() - g.lastRefresh)} ago` : '; tables from the subscriptions (refresh=true re-reads them)'}${g.meshcop?.nodes ? `; ${g.meshcop.nodes} node(s) seen through a border router (MeshCoP)` : ''}:`,
+    ];
+    for (const n of nodes.slice(0, 40)) {
+        const head =
+            n.kind === 'thread'
+                ? `${n.name}: ${n.role ?? 'role ?'}${n.rloc16 !== null && n.rloc16 !== undefined ? `, RLOC16 0x${n.rloc16.toString(16)}` : ''}${n.partitionId !== null && n.partitionId !== undefined ? `, partition ${n.partitionId}` : ''}${n.online ? '' : ', OFFLINE'}${n.borderRouter ? ' (border router)' : ''}`
+                : n.kind === 'border-router'
+                  ? `${n.name} [border router${n.role ? ', ' + n.role : ''}]`
+                  : n.kind === 'wifi'
+                    ? `${n.name} [Wi-Fi, RSSI ${n.rssi ?? '?'} dBm = ${n.quality}]`
+                    : n.kind === 'meshcop'
+                      ? `${n.name} [seen through the border router${n.role ? ', ' + n.role : ''}]`
+                      : `${n.name} [not paired with she]`;
+        const links = g.links
+            .filter((l) => l.kind === 'neighbour' && (l.source === n.id || l.target === n.id))
+            .slice(0, 8)
+            .map(
+                (l) =>
+                    `${nameOf(l.source === n.id ? l.target : l.source)} LQI ${l.lqi}${l.rssi !== null && l.rssi !== undefined ? ` ${l.rssi} dBm` : ''}${l.isChild ? ' child' : ''}${l.bidirectional === false ? ' one-way' : ''}`,
+            );
+        lines.push(`- ${head}${links.length ? ` — links: ${links.join('; ')}` : ''}`);
+    }
+    if (nodes.length > 40) lines.push(`… ${nodes.length - 40} more node(s); ask for one device with node.`);
+    const arrows = g.links.filter((l) => l.kind === 'binding');
+    if (arrows.length) lines.push(`Bindings: ${arrows.map((l) => `${nameOf(l.source)} → ${nameOf(l.target)}`).join('; ')}`);
+    return lines.join('\n');
+}
+
+async function toolGetMatterHealth({ node } = {}) {
+    const controller = matterController();
+    if (!controller) return 'Matter controller not available.';
+    const want = node ? resolveNodeId(controller, node) : null;
+    if (node && !want) return `No Matter device "${node}".`;
+    const lines = [];
+    const dh = matterModule('device-health');
+    if (dh) {
+        const h = dh.listHealth();
+        const nodes = h.nodes.filter((n) => !want || n.nodeId === want);
+        lines.push(`Devices (${h.val}${h.alerts.length ? `, ${h.alerts.length} alert(s)` : ''}):`);
+        for (const n of nodes) {
+            const bat = n.battery
+                ? `battery ${n.battery.percent !== null ? n.battery.percent + ' %' : (n.battery.level ?? '?')}${n.battery.state && n.battery.state !== 'unknown' ? ' ' + n.battery.state : ''}`
+                : 'no battery info';
+            lines.push(
+                `- ${n.name ?? 'node ' + n.nodeId}: ${n.online === false ? `OFFLINE since ${n.since ? isoShort(n.since) : '?'}` : n.online ? `online since ${n.since ? isoShort(n.since) : '?'}` : 'state unknown'}; last seen ${n.lastSeen ? ago(Date.now() - n.lastSeen) + ' ago' : 'never'}; ${bat}${n.offlineCount7d ? `; ${n.offlineCount7d} offline period(s) in 7 days` : ''}${n.alerts.length ? `; ALERT: ${n.alerts.map((a) => a.message).join('; ')}` : ''}`,
+            );
+        }
+    }
+    const th = matterModule('thread-health');
+    if (th && !want) {
+        const t = th.status();
+        lines.push(
+            `\nThread (${t.val}): ${t.active.length ? t.active.map((a) => `${a.kind}: ${a.message} (since ${isoShort(a.since)})`).join('; ') : 'no active alert'}${
+                t.history.length
+                    ? `; last events: ${t.history
+                          .slice(0, 3)
+                          .map((e) => `${isoShort(e.at)} ${e.event} ${e.kind}`)
+                          .join(', ')}`
+                    : ''
+            }`,
+        );
+    }
+    if (typeof controller.listUpdates === 'function') {
+        try {
+            const u = await withTimeout(controller.listUpdates(), 5000);
+            const avail = u.nodes.filter((n) => n.available && (!want || n.nodeId === want));
+            const running = u.nodes.filter((n) => n.pending && (!want || n.nodeId === want));
+            if (avail.length || running.length)
+                lines.push(
+                    `\nFirmware: ${avail
+                        .map((n) => `${n.name ?? n.nodeId} ${n.softwareVersionString ?? n.softwareVersion} → ${n.available.softwareVersionString} available`)
+                        .concat(running.map((n) => `${n.name ?? n.nodeId} updating (${n.updateStateName ?? n.pending.status})`))
+                        .join('; ')}`,
+                );
+            else if (u.available) lines.push('\nFirmware: no update offered by the ledger for any device.');
+        } catch {
+            /* optional */
+        }
+    }
+    return lines.join('\n') || 'No health data.';
+}
+
 module.exports = {
     TOOL_DEFINITIONS,
     TOOL_DEFINITIONS_ANTHROPIC,