iobroker.assistant 0.1.2

package/build/lib/tools.js

@@ -0,0 +1,299 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ListCache = exports.LIST_CACHE_TTL_MS = void 0;
+exports.deviceStateIds = deviceStateIds;
+exports.deviceKey = deviceKey;
+exports.isToolAllowed = isToolAllowed;
+exports.buildMcpTools = buildMcpTools;
+/** All control state ids of a `list_devices` device entry. */
+function deviceStateIds(dev) {
+    return Object.values(dev.controls || {})
+        .map(c => c?.stateId)
+        .filter((x) => !!x);
+}
+/**
+ * Stable per-device key used by both the backend write-guard and the admin ACL editor. Keyed by the
+ * device's primary (lexicographically first) control state id — unique per device and independent of the
+ * (often non-unique) type-detector name, so two "SET" controls no longer collide on one ACL entry.
+ */
+function deviceKey(stateIds) {
+    return [...stateIds].sort()[0] || '';
+}
+/** Maps every known `@iobroker/mcp-server` tool to an access category. */
+const TOOL_CATEGORY = {
+    get_states: 'stateRead',
+    list_devices: 'devices',
+    list_rooms: 'devices',
+    list_functions: 'devices',
+    set_state: 'stateWrite',
+    set_states: 'stateWrite',
+    get_object: 'objectReadAll',
+    search_objects: 'objectReadAll',
+    get_logs: 'logRead',
+    write_log: 'logWrite',
+    history_query: 'history',
+    read_file: 'files',
+    list_files: 'files',
+    file_exists: 'files',
+    system_info: 'system',
+    list_hosts: 'system',
+    list_instances: 'system',
+    list_adapters: 'system',
+    search_adapter_repository: 'system',
+    ping_host: 'system',
+    set_object: 'objectChange',
+    delete_object: 'objectChange',
+    create_state: 'objectChange',
+    create_scene: 'objectChange',
+    write_file: 'objectChange',
+    delete_file: 'objectChange',
+    rename_file: 'objectChange',
+    mkdir: 'objectChange',
+};
+/**
+ * Read-only, system-wide-scan tools whose results are stable enough to serve from a short-TTL cache.
+ * Each of these runs the ioBroker type-detector over *all* objects (`list_devices` alone does five
+ * full `getObjectView` scans), so repeat calls inside one conversation are the main avoidable cost.
+ */
+const CACHEABLE_TOOLS = new Set(['list_devices', 'list_rooms', 'list_functions']);
+/** Default lifetime of a cached device/room/function listing (ms). */
+exports.LIST_CACHE_TTL_MS = 30_000;
+/**
+ * Tiny time-based cache: memoizes a tool result per (tool, args) for {@link ttlMs}. Not invalidated on
+ * object changes — a freshly added device appears after at most one TTL, which is fine for an assistant.
+ * Call {@link ListCache.clear} to force a refresh (e.g. from an `objectChange` subscription).
+ */
+class ListCache {
+    ttlMs;
+    now;
+    store = new Map();
+    constructor(ttlMs = exports.LIST_CACHE_TTL_MS, now = Date.now) {
+        this.ttlMs = ttlMs;
+        this.now = now;
+    }
+    async run(key, produce) {
+        const hit = this.store.get(key);
+        const now = this.now();
+        if (hit && now - hit.at < this.ttlMs) {
+            return hit.val;
+        }
+        const val = await produce();
+        this.store.set(key, { at: now, val });
+        return val;
+    }
+    clear() {
+        this.store.clear();
+    }
+}
+exports.ListCache = ListCache;
+/** Decide whether a tool is allowed by the current access configuration. Unknown tools are denied. */
+function isToolAllowed(name, access) {
+    switch (TOOL_CATEGORY[name]) {
+        case 'stateRead':
+        case 'devices':
+            return true; // reading device/state values is always allowed
+        case 'stateWrite':
+            return access.allowWriteStates;
+        case 'objectReadAll':
+            return access.readObjects === 'all';
+        case 'logRead':
+            return access.allowReadLogs;
+        case 'logWrite':
+            return access.allowWriteLogs;
+        case 'history':
+            return access.allowHistory;
+        case 'files':
+            return access.allowFiles;
+        case 'system':
+            return access.allowSystemInfo;
+        case 'objectChange':
+            return access.allowObjectChange;
+        default:
+            return false; // unknown/unmapped tool → deny (safe default for an access list)
+    }
+}
+/** Device types that default to write-disabled (must be explicitly allowed) for safety, e.g. door locks. */
+const DEFAULT_WRITE_FALSE_TYPES = new Set(['lock']);
+/**
+ * Build the stateId → deviceKey map and the set of keys that default to write-disabled (e.g. locks),
+ * from the MCP `list_devices` tool (best-effort; empty on any error).
+ */
+async function loadStateDeviceMap(mcp) {
+    const stateToKey = new Map();
+    const defaultWriteFalse = new Set();
+    try {
+        const res = await mcp.callTool('list_devices', {});
+        const parsed = JSON.parse(res.text);
+        for (const room of parsed.data?.rooms || []) {
+            for (const dev of room.devicesInRoom || []) {
+                const ids = deviceStateIds(dev);
+                const key = deviceKey(ids);
+                // Every control of the device shares the device's key, so the write-guard resolves any
+                // of its states to the same ACL entry.
+                for (const id of ids) {
+                    stateToKey.set(id, key);
+                }
+                if (DEFAULT_WRITE_FALSE_TYPES.has(String(dev.deviceType ?? ''))) {
+                    defaultWriteFalse.add(key);
+                }
+            }
+        }
+    }
+    catch {
+        /* no device map → no per-device enforcement */
+    }
+    return { stateToKey, defaultWriteFalse };
+}
+/** Device types dropped from `list_devices` so the LLM never treats them as controllable devices. */
+const HIDDEN_LLM_TYPES = new Set(['button']);
+/**
+ * Post-process a `list_devices` result for the LLM: drop hidden types (write-only buttons) and devices
+ * the user set to read-disabled (`acl[key].read === false`), and — when a resolver is given — rewrite
+ * each `deviceName` to the friendly name (smartName → parent name). Original text on any parse problem.
+ */
+async function postProcessListDevices(text, acl, resolveName) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+    const rooms = parsed.data?.rooms;
+    if (!Array.isArray(rooms)) {
+        return text;
+    }
+    for (const room of rooms) {
+        const kept = (room.devicesInRoom || []).filter(d => {
+            if (HIDDEN_LLM_TYPES.has(String(d.deviceType ?? ''))) {
+                return false;
+            }
+            const key = deviceKey(deviceStateIds(d));
+            return !(key && acl[key]?.read === false); // hide read-disabled devices from the LLM
+        });
+        const trimmed = [];
+        for (const dev of kept) {
+            const ids = deviceStateIds(dev);
+            const name = resolveName && ids.length
+                ? (await resolveName(deviceKey(ids), String(dev.deviceName ?? ''))) || dev.deviceName
+                : dev.deviceName;
+            // Keep only what the LLM needs to act (name/type + controlType→{stateId,writable}); drop the
+            // verbose role/unit/min/max/ioBrokerValueType/friendlyDeviceNames to cut tokens & latency.
+            const controls = {};
+            for (const [ct, c] of Object.entries(dev.controls || {})) {
+                controls[ct] = { stateId: c?.stateId, writable: c?.writable };
+            }
+            trimmed.push({ deviceName: name, deviceType: dev.deviceType, controls });
+        }
+        room.devicesInRoom = trimmed;
+    }
+    return JSON.stringify(parsed);
+}
+/** Wrap `get_states` so it drops values of devices the user set to read-disabled. */
+function guardRead(baseRun, stateToKey, acl) {
+    return async (args) => {
+        const text = (await baseRun(args));
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+        const states = parsed.data?.states;
+        if (Array.isArray(states) && parsed.data) {
+            parsed.data.states = states.filter(s => {
+                const key = s?.id ? stateToKey.get(s.id) : undefined;
+                return !(key && acl[key]?.read === false);
+            });
+        }
+        return JSON.stringify(parsed);
+    };
+}
+/**
+ * Wrap a state-writing tool so it refuses writes to states of devices the user marked read-only.
+ * Write is allowed when the explicit ACL entry says so; without an entry, the device type's default
+ * applies (write-disabled for {@link DEFAULT_WRITE_FALSE_TYPES} like locks, allowed otherwise).
+ */
+function guardWrite(name, baseRun, stateToKey, acl, defaultWriteFalse) {
+    return async (args) => {
+        const ids = name === 'set_states'
+            ? (args.states || []).map(s => s?.id).filter((x) => !!x)
+            : typeof args.id === 'string'
+                ? [args.id]
+                : [];
+        for (const id of ids) {
+            const key = stateToKey.get(id);
+            if (!key) {
+                continue;
+            }
+            const entry = acl[key];
+            const writeAllowed = entry ? entry.write !== false : !defaultWriteFalse.has(key);
+            if (!writeAllowed) {
+                return JSON.stringify({
+                    ok: false,
+                    error: `Writing "${id}" is not allowed: device "${key}" is read-only in the assistant settings.`,
+                });
+            }
+        }
+        return baseRun(args);
+    };
+}
+/**
+ * Build the LLM tool set from the in-process ioBroker MCP server, filtered by the access config and
+ * enforcing the per-device write ACL.
+ *
+ * All tools come from `@iobroker/mcp-server` — nothing is duplicated here. Gating layers:
+ *  1. `createInProcessMcp({ allowSetState, allowObjectChange })` — which tools exist at all.
+ *  2. `isToolAllowed()` — fine-grained category toggles (logs/history/files/object-read scope/…).
+ *  3. `guardWrite()` — per-device write ACL (`access.deviceAcl`), e.g. keep a lock read-only.
+ */
+async function buildMcpTools(mcp, access, cache = new ListCache(), resolveName) {
+    const infos = await mcp.listTools();
+    const acl = access.deviceAcl || {};
+    // Write guard: whenever writing is enabled (explicit ACL + type defaults like locks).
+    const enforceWrite = access.allowWriteStates;
+    // Read guard: whenever any device is set read-disabled (hide it from list_devices + get_states).
+    const enforceRead = Object.values(acl).some(a => a && a.read === false);
+    const { stateToKey, defaultWriteFalse } = enforceWrite || enforceRead
+        ? await loadStateDeviceMap(mcp)
+        : { stateToKey: new Map(), defaultWriteFalse: new Set() };
+    const tools = [];
+    const denied = [];
+    for (const info of infos) {
+        if (!isToolAllowed(info.name, access)) {
+            denied.push(info.name);
+            continue;
+        }
+        const callTool = async (args) => {
+            const text = (await mcp.callTool(info.name, args)).text;
+            // For the LLM: drop buttons + read-disabled devices, and use friendly names.
+            return info.name === 'list_devices' ? postProcessListDevices(text, acl, resolveName) : text;
+        };
+        // Serve stable, expensive read-only listings from the short-TTL cache; everything else runs live.
+        const baseRun = CACHEABLE_TOOLS.has(info.name)
+            ? (args) => cache.run(`${info.name}:${JSON.stringify(args ?? {})}`, () => callTool(args))
+            : callTool;
+        let run = baseRun;
+        if (enforceWrite && (info.name === 'set_state' || info.name === 'set_states')) {
+            run = guardWrite(info.name, baseRun, stateToKey, acl, defaultWriteFalse);
+        }
+        else if (enforceRead && info.name === 'get_states') {
+            run = guardRead(baseRun, stateToKey, acl);
+        }
+        tools.push({ name: info.name, description: info.description || '', parameters: info.inputSchema, run });
+    }
+    // Synthetic (non-MCP) tool: lets the model bust the device/room cache and re-scan. Useful when a
+    // device the user mentions is missing from list_devices (stale cache) or was just added/renamed.
+    tools.push({
+        name: 'refresh_device_cache',
+        description: 'Clear the cached device, room and function listings so the next list_devices, list_rooms or list_functions call performs a fresh scan. Call this when a device or room the user mentions is not in the list, or when the user says a device was just added, renamed or reassigned, then retry.',
+        parameters: { type: 'object', properties: {}, additionalProperties: false },
+        run: () => {
+            cache.clear();
+            return Promise.resolve(JSON.stringify({ ok: true, data: { cleared: true } }));
+        },
+    });
+    return { tools, denied, cache };
+}
+//# sourceMappingURL=tools.js.map

package/build/lib/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../src/lib/tools.ts"],"names":[],"mappings":"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","sourcesContent":["import type { InProcessMcp } from '@iobroker/mcp-server';\n\n/** An LLM-callable tool: name, description, JSON-schema parameters, and a runner. */\nexport interface Tool {\n    name: string;\n    description: string;\n    /** JSON schema for the tool arguments. */\n    parameters: Record<string, unknown>;\n    run(args: Record<string, unknown>): Promise<unknown>;\n}\n\n/** Per-device read/write override, keyed by {@link deviceKey}. Absent → governed by the coarse toggles. */\nexport type DeviceAcl = Record<string, { read: boolean; write: boolean }>;\n\n/** The access toggles from the adapter config that gate which MCP tools the LLM may use. */\nexport interface ToolAccess {\n    allowWriteStates: boolean;\n    allowObjectChange: boolean;\n    readObjects: 'devices' | 'all';\n    allowReadLogs: boolean;\n    allowWriteLogs: boolean;\n    allowHistory: boolean;\n    allowFiles: boolean;\n    allowSystemInfo: boolean;\n    deviceAcl: DeviceAcl;\n}\n\n/** One `list_devices` device entry (as far as we care: its controls' state ids). */\nexport interface McpDeviceEntry {\n    deviceName?: string;\n    deviceType?: string;\n    controls?: Record<string, { stateId?: string; writable?: boolean }>;\n}\n\n/** All control state ids of a `list_devices` device entry. */\nexport function deviceStateIds(dev: McpDeviceEntry): string[] {\n    return Object.values(dev.controls || {})\n        .map(c => c?.stateId)\n        .filter((x): x is string => !!x);\n}\n\n/**\n * Stable per-device key used by both the backend write-guard and the admin ACL editor. Keyed by the\n * device's primary (lexicographically first) control state id — unique per device and independent of the\n * (often non-unique) type-detector name, so two \"SET\" controls no longer collide on one ACL entry.\n */\nexport function deviceKey(stateIds: string[]): string {\n    return [...stateIds].sort()[0] || '';\n}\n\ntype ToolCategory =\n    | 'stateRead'\n    | 'stateWrite'\n    | 'devices'\n    | 'objectReadAll'\n    | 'logRead'\n    | 'logWrite'\n    | 'history'\n    | 'files'\n    | 'system'\n    | 'objectChange';\n\n/** Maps every known `@iobroker/mcp-server` tool to an access category. */\nconst TOOL_CATEGORY: Record<string, ToolCategory> = {\n    get_states: 'stateRead',\n    list_devices: 'devices',\n    list_rooms: 'devices',\n    list_functions: 'devices',\n    set_state: 'stateWrite',\n    set_states: 'stateWrite',\n    get_object: 'objectReadAll',\n    search_objects: 'objectReadAll',\n    get_logs: 'logRead',\n    write_log: 'logWrite',\n    history_query: 'history',\n    read_file: 'files',\n    list_files: 'files',\n    file_exists: 'files',\n    system_info: 'system',\n    list_hosts: 'system',\n    list_instances: 'system',\n    list_adapters: 'system',\n    search_adapter_repository: 'system',\n    ping_host: 'system',\n    set_object: 'objectChange',\n    delete_object: 'objectChange',\n    create_state: 'objectChange',\n    create_scene: 'objectChange',\n    write_file: 'objectChange',\n    delete_file: 'objectChange',\n    rename_file: 'objectChange',\n    mkdir: 'objectChange',\n};\n\n/**\n * Read-only, system-wide-scan tools whose results are stable enough to serve from a short-TTL cache.\n * Each of these runs the ioBroker type-detector over *all* objects (`list_devices` alone does five\n * full `getObjectView` scans), so repeat calls inside one conversation are the main avoidable cost.\n */\nconst CACHEABLE_TOOLS = new Set(['list_devices', 'list_rooms', 'list_functions']);\n\n/** Default lifetime of a cached device/room/function listing (ms). */\nexport const LIST_CACHE_TTL_MS = 30_000;\n\n/**\n * Tiny time-based cache: memoizes a tool result per (tool, args) for {@link ttlMs}. Not invalidated on\n * object changes — a freshly added device appears after at most one TTL, which is fine for an assistant.\n * Call {@link ListCache.clear} to force a refresh (e.g. from an `objectChange` subscription).\n */\nexport class ListCache {\n    private readonly store = new Map<string, { at: number; val: string }>();\n\n    constructor(\n        private readonly ttlMs: number = LIST_CACHE_TTL_MS,\n        private readonly now: () => number = Date.now,\n    ) {}\n\n    async run(key: string, produce: () => Promise<string>): Promise<string> {\n        const hit = this.store.get(key);\n        const now = this.now();\n        if (hit && now - hit.at < this.ttlMs) {\n            return hit.val;\n        }\n        const val = await produce();\n        this.store.set(key, { at: now, val });\n        return val;\n    }\n\n    clear(): void {\n        this.store.clear();\n    }\n}\n\n/** Decide whether a tool is allowed by the current access configuration. Unknown tools are denied. */\nexport function isToolAllowed(name: string, access: ToolAccess): boolean {\n    switch (TOOL_CATEGORY[name]) {\n        case 'stateRead':\n        case 'devices':\n            return true; // reading device/state values is always allowed\n        case 'stateWrite':\n            return access.allowWriteStates;\n        case 'objectReadAll':\n            return access.readObjects === 'all';\n        case 'logRead':\n            return access.allowReadLogs;\n        case 'logWrite':\n            return access.allowWriteLogs;\n        case 'history':\n            return access.allowHistory;\n        case 'files':\n            return access.allowFiles;\n        case 'system':\n            return access.allowSystemInfo;\n        case 'objectChange':\n            return access.allowObjectChange;\n        default:\n            return false; // unknown/unmapped tool → deny (safe default for an access list)\n    }\n}\n\n/** Device types that default to write-disabled (must be explicitly allowed) for safety, e.g. door locks. */\nconst DEFAULT_WRITE_FALSE_TYPES = new Set(['lock']);\n\n/**\n * Build the stateId → deviceKey map and the set of keys that default to write-disabled (e.g. locks),\n * from the MCP `list_devices` tool (best-effort; empty on any error).\n */\nasync function loadStateDeviceMap(\n    mcp: InProcessMcp,\n): Promise<{ stateToKey: Map<string, string>; defaultWriteFalse: Set<string> }> {\n    const stateToKey = new Map<string, string>();\n    const defaultWriteFalse = new Set<string>();\n    try {\n        const res = await mcp.callTool('list_devices', {});\n        const parsed = JSON.parse(res.text) as {\n            data?: { rooms?: { devicesInRoom?: McpDeviceEntry[] }[] };\n        };\n        for (const room of parsed.data?.rooms || []) {\n            for (const dev of room.devicesInRoom || []) {\n                const ids = deviceStateIds(dev);\n                const key = deviceKey(ids);\n                // Every control of the device shares the device's key, so the write-guard resolves any\n                // of its states to the same ACL entry.\n                for (const id of ids) {\n                    stateToKey.set(id, key);\n                }\n                if (DEFAULT_WRITE_FALSE_TYPES.has(String(dev.deviceType ?? ''))) {\n                    defaultWriteFalse.add(key);\n                }\n            }\n        }\n    } catch {\n        /* no device map → no per-device enforcement */\n    }\n    return { stateToKey, defaultWriteFalse };\n}\n\n/** JSON shape of a `list_devices` result, for post-processing the device names the LLM sees. */\ninterface ListDevicesResult {\n    data?: { rooms?: { devicesInRoom?: McpDeviceEntry[] }[] };\n}\n\n/** Device types dropped from `list_devices` so the LLM never treats them as controllable devices. */\nconst HIDDEN_LLM_TYPES = new Set(['button']);\n\n/**\n * Post-process a `list_devices` result for the LLM: drop hidden types (write-only buttons) and devices\n * the user set to read-disabled (`acl[key].read === false`), and — when a resolver is given — rewrite\n * each `deviceName` to the friendly name (smartName → parent name). Original text on any parse problem.\n */\nasync function postProcessListDevices(\n    text: string,\n    acl: DeviceAcl,\n    resolveName?: (stateId: string, fallback: string) => Promise<string>,\n): Promise<string> {\n    let parsed: ListDevicesResult;\n    try {\n        parsed = JSON.parse(text) as ListDevicesResult;\n    } catch {\n        return text;\n    }\n    const rooms = parsed.data?.rooms;\n    if (!Array.isArray(rooms)) {\n        return text;\n    }\n    for (const room of rooms) {\n        const kept = (room.devicesInRoom || []).filter(d => {\n            if (HIDDEN_LLM_TYPES.has(String(d.deviceType ?? ''))) {\n                return false;\n            }\n            const key = deviceKey(deviceStateIds(d));\n            return !(key && acl[key]?.read === false); // hide read-disabled devices from the LLM\n        });\n        const trimmed: McpDeviceEntry[] = [];\n        for (const dev of kept) {\n            const ids = deviceStateIds(dev);\n            const name =\n                resolveName && ids.length\n                    ? (await resolveName(deviceKey(ids), String(dev.deviceName ?? ''))) || dev.deviceName\n                    : dev.deviceName;\n            // Keep only what the LLM needs to act (name/type + controlType→{stateId,writable}); drop the\n            // verbose role/unit/min/max/ioBrokerValueType/friendlyDeviceNames to cut tokens & latency.\n            const controls: Record<string, { stateId?: string; writable?: boolean }> = {};\n            for (const [ct, c] of Object.entries(dev.controls || {})) {\n                controls[ct] = { stateId: c?.stateId, writable: c?.writable };\n            }\n            trimmed.push({ deviceName: name, deviceType: dev.deviceType, controls });\n        }\n        room.devicesInRoom = trimmed;\n    }\n    return JSON.stringify(parsed);\n}\n\n/** Wrap `get_states` so it drops values of devices the user set to read-disabled. */\nfunction guardRead(\n    baseRun: (args: Record<string, unknown>) => Promise<unknown>,\n    stateToKey: Map<string, string>,\n    acl: DeviceAcl,\n): (args: Record<string, unknown>) => Promise<unknown> {\n    return async (args: Record<string, unknown>): Promise<unknown> => {\n        const text = (await baseRun(args)) as string;\n        let parsed: { data?: { states?: { id?: string }[] } };\n        try {\n            parsed = JSON.parse(text) as { data?: { states?: { id?: string }[] } };\n        } catch {\n            return text;\n        }\n        const states = parsed.data?.states;\n        if (Array.isArray(states) && parsed.data) {\n            parsed.data.states = states.filter(s => {\n                const key = s?.id ? stateToKey.get(s.id) : undefined;\n                return !(key && acl[key]?.read === false);\n            });\n        }\n        return JSON.stringify(parsed);\n    };\n}\n\n/**\n * Wrap a state-writing tool so it refuses writes to states of devices the user marked read-only.\n * Write is allowed when the explicit ACL entry says so; without an entry, the device type's default\n * applies (write-disabled for {@link DEFAULT_WRITE_FALSE_TYPES} like locks, allowed otherwise).\n */\nfunction guardWrite(\n    name: string,\n    baseRun: (args: Record<string, unknown>) => Promise<unknown>,\n    stateToKey: Map<string, string>,\n    acl: DeviceAcl,\n    defaultWriteFalse: Set<string>,\n): (args: Record<string, unknown>) => Promise<unknown> {\n    return async (args: Record<string, unknown>): Promise<unknown> => {\n        const ids =\n            name === 'set_states'\n                ? ((args.states as { id?: string }[] | undefined) || []).map(s => s?.id).filter((x): x is string => !!x)\n                : typeof args.id === 'string'\n                  ? [args.id]\n                  : [];\n        for (const id of ids) {\n            const key = stateToKey.get(id);\n            if (!key) {\n                continue;\n            }\n            const entry = acl[key];\n            const writeAllowed = entry ? entry.write !== false : !defaultWriteFalse.has(key);\n            if (!writeAllowed) {\n                return JSON.stringify({\n                    ok: false,\n                    error: `Writing \"${id}\" is not allowed: device \"${key}\" is read-only in the assistant settings.`,\n                });\n            }\n        }\n        return baseRun(args);\n    };\n}\n\n/**\n * Build the LLM tool set from the in-process ioBroker MCP server, filtered by the access config and\n * enforcing the per-device write ACL.\n *\n * All tools come from `@iobroker/mcp-server` — nothing is duplicated here. Gating layers:\n *  1. `createInProcessMcp({ allowSetState, allowObjectChange })` — which tools exist at all.\n *  2. `isToolAllowed()` — fine-grained category toggles (logs/history/files/object-read scope/…).\n *  3. `guardWrite()` — per-device write ACL (`access.deviceAcl`), e.g. keep a lock read-only.\n */\nexport async function buildMcpTools(\n    mcp: InProcessMcp,\n    access: ToolAccess,\n    cache: ListCache = new ListCache(),\n    resolveName?: (stateId: string, fallback: string) => Promise<string>,\n): Promise<{ tools: Tool[]; denied: string[]; cache: ListCache }> {\n    const infos = await mcp.listTools();\n    const acl = access.deviceAcl || {};\n    // Write guard: whenever writing is enabled (explicit ACL + type defaults like locks).\n    const enforceWrite = access.allowWriteStates;\n    // Read guard: whenever any device is set read-disabled (hide it from list_devices + get_states).\n    const enforceRead = Object.values(acl).some(a => a && a.read === false);\n    const { stateToKey, defaultWriteFalse } =\n        enforceWrite || enforceRead\n            ? await loadStateDeviceMap(mcp)\n            : { stateToKey: new Map<string, string>(), defaultWriteFalse: new Set<string>() };\n\n    const tools: Tool[] = [];\n    const denied: string[] = [];\n    for (const info of infos) {\n        if (!isToolAllowed(info.name, access)) {\n            denied.push(info.name);\n            continue;\n        }\n        const callTool = async (args: Record<string, unknown>): Promise<string> => {\n            const text = (await mcp.callTool(info.name, args)).text;\n            // For the LLM: drop buttons + read-disabled devices, and use friendly names.\n            return info.name === 'list_devices' ? postProcessListDevices(text, acl, resolveName) : text;\n        };\n        // Serve stable, expensive read-only listings from the short-TTL cache; everything else runs live.\n        const baseRun: (args: Record<string, unknown>) => Promise<unknown> = CACHEABLE_TOOLS.has(info.name)\n            ? (args): Promise<string> => cache.run(`${info.name}:${JSON.stringify(args ?? {})}`, () => callTool(args))\n            : callTool;\n        let run = baseRun;\n        if (enforceWrite && (info.name === 'set_state' || info.name === 'set_states')) {\n            run = guardWrite(info.name, baseRun, stateToKey, acl, defaultWriteFalse);\n        } else if (enforceRead && info.name === 'get_states') {\n            run = guardRead(baseRun, stateToKey, acl);\n        }\n        tools.push({ name: info.name, description: info.description || '', parameters: info.inputSchema, run });\n    }\n\n    // Synthetic (non-MCP) tool: lets the model bust the device/room cache and re-scan. Useful when a\n    // device the user mentions is missing from list_devices (stale cache) or was just added/renamed.\n    tools.push({\n        name: 'refresh_device_cache',\n        description:\n            'Clear the cached device, room and function listings so the next list_devices, list_rooms or list_functions call performs a fresh scan. Call this when a device or room the user mentions is not in the list, or when the user says a device was just added, renamed or reassigned, then retry.',\n        parameters: { type: 'object', properties: {}, additionalProperties: false },\n        run: (): Promise<string> => {\n            cache.clear();\n            return Promise.resolve(JSON.stringify({ ok: true, data: { cleared: true } }));\n        },\n    });\n\n    return { tools, denied, cache };\n}\n"]}

package/build/lib/voice/aws.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AwsTts = exports.AwsStt = void 0;
+exports.listPollyVoices = listPollyVoices;
+/**
+ * AWS speech engines: STT via Amazon Transcribe (streaming) and TTS via Amazon Polly.
+ * Credentials: accessKeyId + secretAccessKey + region.
+ */
+const client_polly_1 = require("@aws-sdk/client-polly");
+const client_transcribe_streaming_1 = require("@aws-sdk/client-transcribe-streaming");
+const lang_1 = require("./lang");
+/** Reasonable default Polly voice per language when none is configured. */
+const DEFAULT_POLLY_VOICE = {
+    de: 'Vicki',
+    en: 'Joanna',
+    ru: 'Tatyana',
+    fr: 'Lea',
+    it: 'Bianca',
+    es: 'Lucia',
+    nl: 'Laura',
+    pl: 'Ewa',
+    pt: 'Ines',
+};
+/** ~100 ms of 16 kHz mono 16-bit PCM per Transcribe audio chunk. */
+const STT_CHUNK_BYTES = 3200;
+/** List available Polly voice ids, optionally filtered by language (locale, e.g. 'de-DE'). */
+async function listPollyVoices(creds, languageCode) {
+    const client = new client_polly_1.PollyClient({
+        region: creds.region,
+        credentials: { accessKeyId: creds.accessKeyId, secretAccessKey: creds.secretAccessKey },
+    });
+    const res = await client.send(new client_polly_1.DescribeVoicesCommand(languageCode ? { LanguageCode: languageCode } : {}));
+    return (res.Voices || []).map(v => v.Id).filter((id) => !!id);
+}
+class AwsStt {
+    client;
+    constructor(creds) {
+        this.client = new client_transcribe_streaming_1.TranscribeStreamingClient({
+            region: creds.region,
+            credentials: { accessKeyId: creds.accessKeyId, secretAccessKey: creds.secretAccessKey },
+        });
+    }
+    // Note: the SttEngine `hints` vocabulary is intentionally not applied here. Amazon Transcribe biases
+    // only via a *custom vocabulary* that must be created/registered ahead of time (CreateVocabulary) and
+    // referenced by name — there is no inline per-request word list for streaming. So we skip biasing for AWS.
+    async transcribe(pcm, sampleRate, lang) {
+        // Must be an async generator: Transcribe's AudioStream is an AsyncIterable.
+        // eslint-disable-next-line @typescript-eslint/require-await
+        async function* audio() {
+            for (let off = 0; off < pcm.length; off += STT_CHUNK_BYTES) {
+                yield { AudioEvent: { AudioChunk: pcm.subarray(off, off + STT_CHUNK_BYTES) } };
+            }
+        }
+        const resp = await this.client.send(new client_transcribe_streaming_1.StartStreamTranscriptionCommand({
+            LanguageCode: (0, lang_1.isoToLocale)(lang),
+            MediaSampleRateHertz: sampleRate,
+            MediaEncoding: 'pcm',
+            AudioStream: audio(),
+        }));
+        let text = '';
+        for await (const event of resp.TranscriptResultStream || []) {
+            for (const result of event.TranscriptEvent?.Transcript?.Results || []) {
+                const transcript = result.Alternatives?.[0]?.Transcript;
+                if (!result.IsPartial && transcript) {
+                    text += (text ? ' ' : '') + transcript;
+                }
+            }
+        }
+        return text.trim();
+    }
+}
+exports.AwsStt = AwsStt;
+class AwsTts {
+    voice;
+    client;
+    constructor(creds, 
+    /** Polly VoiceId (e.g. 'Vicki', 'Tatyana'); empty → default per language. */
+    voice) {
+        this.voice = voice;
+        this.client = new client_polly_1.PollyClient({
+            region: creds.region,
+            credentials: { accessKeyId: creds.accessKeyId, secretAccessKey: creds.secretAccessKey },
+        });
+    }
+    async synthesize(text, lang) {
+        const iso = (lang || 'en').split('-')[0].toLowerCase();
+        const voice = this.voice || DEFAULT_POLLY_VOICE[iso] || 'Joanna';
+        const resp = await this.client.send(new client_polly_1.SynthesizeSpeechCommand({
+            Text: text,
+            OutputFormat: 'pcm', // 16-bit signed 1-channel little-endian
+            SampleRate: '16000',
+            VoiceId: voice,
+        }));
+        if (!resp.AudioStream) {
+            throw new Error('Polly returned no audio stream');
+        }
+        const bytes = await resp.AudioStream.transformToByteArray();
+        return { pcm: Buffer.from(bytes), sampleRate: 16000 };
+    }
+}
+exports.AwsTts = AwsTts;
+//# sourceMappingURL=aws.js.map

package/build/lib/voice/aws.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"aws.js","sourceRoot":"","sources":["../../../src/lib/voice/aws.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * AWS speech engines: STT via Amazon Transcribe (streaming) and TTS via Amazon Polly.\n * Credentials: accessKeyId + secretAccessKey + region.\n */\nimport {\n    PollyClient,\n    SynthesizeSpeechCommand,\n    DescribeVoicesCommand,\n    type VoiceId,\n    type LanguageCode as PollyLanguageCode,\n} from '@aws-sdk/client-polly';\nimport {\n    TranscribeStreamingClient,\n    StartStreamTranscriptionCommand,\n    type AudioStream,\n    type LanguageCode,\n} from '@aws-sdk/client-transcribe-streaming';\nimport { isoToLocale } from './lang';\nimport type { SttEngine } from './stt';\nimport type { TtsEngine, TtsResult } from './tts';\n\nexport interface AwsCreds {\n    accessKeyId: string;\n    secretAccessKey: string;\n    region: string;\n}\n\n/** Reasonable default Polly voice per language when none is configured. */\nconst DEFAULT_POLLY_VOICE: Record<string, string> = {\n    de: 'Vicki',\n    en: 'Joanna',\n    ru: 'Tatyana',\n    fr: 'Lea',\n    it: 'Bianca',\n    es: 'Lucia',\n    nl: 'Laura',\n    pl: 'Ewa',\n    pt: 'Ines',\n};\n\n/** ~100 ms of 16 kHz mono 16-bit PCM per Transcribe audio chunk. */\nconst STT_CHUNK_BYTES = 3200;\n\n/** List available Polly voice ids, optionally filtered by language (locale, e.g. 'de-DE'). */\nexport async function listPollyVoices(creds: AwsCreds, languageCode: string): Promise<string[]> {\n    const client = new PollyClient({\n        region: creds.region,\n        credentials: { accessKeyId: creds.accessKeyId, secretAccessKey: creds.secretAccessKey },\n    });\n    const res = await client.send(\n        new DescribeVoicesCommand(languageCode ? { LanguageCode: languageCode as PollyLanguageCode } : {}),\n    );\n    return (res.Voices || []).map(v => v.Id).filter((id): id is VoiceId => !!id);\n}\n\nexport class AwsStt implements SttEngine {\n    private readonly client: TranscribeStreamingClient;\n\n    constructor(creds: AwsCreds) {\n        this.client = new TranscribeStreamingClient({\n            region: creds.region,\n            credentials: { accessKeyId: creds.accessKeyId, secretAccessKey: creds.secretAccessKey },\n        });\n    }\n\n    // Note: the SttEngine `hints` vocabulary is intentionally not applied here. Amazon Transcribe biases\n    // only via a *custom vocabulary* that must be created/registered ahead of time (CreateVocabulary) and\n    // referenced by name — there is no inline per-request word list for streaming. So we skip biasing for AWS.\n    async transcribe(pcm: Buffer, sampleRate: number, lang: string): Promise<string> {\n        // Must be an async generator: Transcribe's AudioStream is an AsyncIterable.\n        // eslint-disable-next-line @typescript-eslint/require-await\n        async function* audio(): AsyncGenerator<AudioStream> {\n            for (let off = 0; off < pcm.length; off += STT_CHUNK_BYTES) {\n                yield { AudioEvent: { AudioChunk: pcm.subarray(off, off + STT_CHUNK_BYTES) } };\n            }\n        }\n\n        const resp = await this.client.send(\n            new StartStreamTranscriptionCommand({\n                LanguageCode: isoToLocale(lang) as LanguageCode,\n                MediaSampleRateHertz: sampleRate,\n                MediaEncoding: 'pcm',\n                AudioStream: audio(),\n            }),\n        );\n\n        let text = '';\n        for await (const event of resp.TranscriptResultStream || []) {\n            for (const result of event.TranscriptEvent?.Transcript?.Results || []) {\n                const transcript = result.Alternatives?.[0]?.Transcript;\n                if (!result.IsPartial && transcript) {\n                    text += (text ? ' ' : '') + transcript;\n                }\n            }\n        }\n        return text.trim();\n    }\n}\n\nexport class AwsTts implements TtsEngine {\n    private readonly client: PollyClient;\n\n    constructor(\n        creds: AwsCreds,\n        /** Polly VoiceId (e.g. 'Vicki', 'Tatyana'); empty → default per language. */\n        private readonly voice: string,\n    ) {\n        this.client = new PollyClient({\n            region: creds.region,\n            credentials: { accessKeyId: creds.accessKeyId, secretAccessKey: creds.secretAccessKey },\n        });\n    }\n\n    async synthesize(text: string, lang: string): Promise<TtsResult> {\n        const iso = (lang || 'en').split('-')[0].toLowerCase();\n        const voice = this.voice || DEFAULT_POLLY_VOICE[iso] || 'Joanna';\n        const resp = await this.client.send(\n            new SynthesizeSpeechCommand({\n                Text: text,\n                OutputFormat: 'pcm', // 16-bit signed 1-channel little-endian\n                SampleRate: '16000',\n                VoiceId: voice as VoiceId,\n            }),\n        );\n        if (!resp.AudioStream) {\n            throw new Error('Polly returned no audio stream');\n        }\n        const bytes = await resp.AudioStream.transformToByteArray();\n        return { pcm: Buffer.from(bytes), sampleRate: 16000 };\n    }\n}\n"]}

package/build/lib/voice/azure.js

@@ -0,0 +1,144 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AzureTts = exports.AzureStt = void 0;
+exports.listAzureVoices = listAzureVoices;
+/**
+ * Azure Cognitive Services Speech engines (STT + TTS).
+ * Credentials: a subscription key + region (e.g. 'westeurope').
+ */
+const sdk = __importStar(require("microsoft-cognitiveservices-speech-sdk"));
+const lang_1 = require("./lang");
+/** List available Azure voices (short names like 'de-DE-KatjaNeural'), optionally filtered by locale. */
+async function listAzureVoices(key, region, locale) {
+    const speechConfig = sdk.SpeechConfig.fromSubscription(key, region);
+    const synth = new sdk.SpeechSynthesizer(speechConfig, null);
+    try {
+        const res = await synth.getVoicesAsync(locale || '');
+        if (res.reason === sdk.ResultReason.VoicesListRetrieved) {
+            return res.voices.map(v => v.shortName);
+        }
+        throw new Error(res.errorDetails || 'Azure voice list failed');
+    }
+    finally {
+        synth.close();
+    }
+}
+/** Azure STT via `recognizeOnceAsync` fed from a PCM push stream (one short utterance). */
+class AzureStt {
+    key;
+    region;
+    constructor(key, region) {
+        this.key = key;
+        this.region = region;
+    }
+    async transcribe(pcm, sampleRate, lang, hints) {
+        const speechConfig = sdk.SpeechConfig.fromSubscription(this.key, this.region);
+        speechConfig.speechRecognitionLanguage = (0, lang_1.isoToLocale)(lang);
+        const format = sdk.AudioStreamFormat.getWaveFormatPCM(sampleRate, 16, 1);
+        const pushStream = sdk.AudioInputStream.createPushStream(format);
+        // The push stream needs a standalone ArrayBuffer (not the pooled Node Buffer view).
+        pushStream.write(pcm.buffer.slice(pcm.byteOffset, pcm.byteOffset + pcm.byteLength));
+        pushStream.close();
+        const recognizer = new sdk.SpeechRecognizer(speechConfig, sdk.AudioConfig.fromStreamInput(pushStream));
+        // A phrase list softly boosts recognition of the given domain vocabulary (device/room names) without
+        // restricting the recognizer to only those words.
+        if (hints?.length) {
+            const phraseList = sdk.PhraseListGrammar.fromRecognizer(recognizer);
+            for (const h of hints) {
+                const term = (h || '').trim();
+                if (term) {
+                    phraseList.addPhrase(term);
+                }
+            }
+        }
+        try {
+            const result = await new Promise((resolve, reject) => {
+                recognizer.recognizeOnceAsync(resolve, reject);
+            });
+            if (result.reason === sdk.ResultReason.RecognizedSpeech) {
+                return result.text.trim();
+            }
+            if (result.reason === sdk.ResultReason.Canceled) {
+                const details = sdk.CancellationDetails.fromResult(result);
+                throw new Error(`Azure STT canceled: ${details.errorDetails || details.reason}`);
+            }
+            return '';
+        }
+        finally {
+            recognizer.close();
+        }
+    }
+}
+exports.AzureStt = AzureStt;
+/** Azure TTS to raw 24 kHz mono 16-bit PCM (no server-side playback). */
+class AzureTts {
+    key;
+    region;
+    voice;
+    constructor(key, region, 
+    /** Full Azure voice name (e.g. 'de-DE-KatjaNeural'); empty → pick by language. */
+    voice) {
+        this.key = key;
+        this.region = region;
+        this.voice = voice;
+    }
+    async synthesize(text, lang) {
+        const speechConfig = sdk.SpeechConfig.fromSubscription(this.key, this.region);
+        speechConfig.speechSynthesisOutputFormat = sdk.SpeechSynthesisOutputFormat.Raw24Khz16BitMonoPcm;
+        if (this.voice) {
+            speechConfig.speechSynthesisVoiceName = this.voice;
+        }
+        else {
+            speechConfig.speechSynthesisLanguage = (0, lang_1.isoToLocale)(lang);
+        }
+        // audioConfig=null → synthesise to memory only, no default-speaker output.
+        const synth = new sdk.SpeechSynthesizer(speechConfig, null);
+        try {
+            const result = await new Promise((resolve, reject) => {
+                synth.speakTextAsync(text, resolve, reject);
+            });
+            if (result.reason === sdk.ResultReason.SynthesizingAudioCompleted) {
+                return { pcm: Buffer.from(result.audioData), sampleRate: 24000 };
+            }
+            throw new Error(`Azure TTS failed: ${result.errorDetails || result.reason}`);
+        }
+        finally {
+            synth.close();
+        }
+    }
+}
+exports.AzureTts = AzureTts;
+//# sourceMappingURL=azure.js.map

package/build/lib/voice/azure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"azure.js","sourceRoot":"","sources":["../../../src/lib/voice/azure.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Azure Cognitive Services Speech engines (STT + TTS).\n * Credentials: a subscription key + region (e.g. 'westeurope').\n */\nimport * as sdk from 'microsoft-cognitiveservices-speech-sdk';\nimport { isoToLocale } from './lang';\nimport type { SttEngine } from './stt';\nimport type { TtsEngine, TtsResult } from './tts';\n\n/** List available Azure voices (short names like 'de-DE-KatjaNeural'), optionally filtered by locale. */\nexport async function listAzureVoices(key: string, region: string, locale: string): Promise<string[]> {\n    const speechConfig = sdk.SpeechConfig.fromSubscription(key, region);\n    const synth = new sdk.SpeechSynthesizer(speechConfig, null);\n    try {\n        const res = await synth.getVoicesAsync(locale || '');\n        if (res.reason === sdk.ResultReason.VoicesListRetrieved) {\n            return res.voices.map(v => v.shortName);\n        }\n        throw new Error(res.errorDetails || 'Azure voice list failed');\n    } finally {\n        synth.close();\n    }\n}\n\n/** Azure STT via `recognizeOnceAsync` fed from a PCM push stream (one short utterance). */\nexport class AzureStt implements SttEngine {\n    constructor(\n        private readonly key: string,\n        private readonly region: string,\n    ) {}\n\n    async transcribe(pcm: Buffer, sampleRate: number, lang: string, hints?: string[]): Promise<string> {\n        const speechConfig = sdk.SpeechConfig.fromSubscription(this.key, this.region);\n        speechConfig.speechRecognitionLanguage = isoToLocale(lang);\n\n        const format = sdk.AudioStreamFormat.getWaveFormatPCM(sampleRate, 16, 1);\n        const pushStream = sdk.AudioInputStream.createPushStream(format);\n        // The push stream needs a standalone ArrayBuffer (not the pooled Node Buffer view).\n        pushStream.write(pcm.buffer.slice(pcm.byteOffset, pcm.byteOffset + pcm.byteLength) as ArrayBuffer);\n        pushStream.close();\n\n        const recognizer = new sdk.SpeechRecognizer(speechConfig, sdk.AudioConfig.fromStreamInput(pushStream));\n        // A phrase list softly boosts recognition of the given domain vocabulary (device/room names) without\n        // restricting the recognizer to only those words.\n        if (hints?.length) {\n            const phraseList = sdk.PhraseListGrammar.fromRecognizer(recognizer);\n            for (const h of hints) {\n                const term = (h || '').trim();\n                if (term) {\n                    phraseList.addPhrase(term);\n                }\n            }\n        }\n        try {\n            const result = await new Promise<sdk.SpeechRecognitionResult>((resolve, reject) => {\n                recognizer.recognizeOnceAsync(resolve, reject);\n            });\n            if (result.reason === sdk.ResultReason.RecognizedSpeech) {\n                return result.text.trim();\n            }\n            if (result.reason === sdk.ResultReason.Canceled) {\n                const details = sdk.CancellationDetails.fromResult(result);\n                throw new Error(`Azure STT canceled: ${details.errorDetails || details.reason}`);\n            }\n            return '';\n        } finally {\n            recognizer.close();\n        }\n    }\n}\n\n/** Azure TTS to raw 24 kHz mono 16-bit PCM (no server-side playback). */\nexport class AzureTts implements TtsEngine {\n    constructor(\n        private readonly key: string,\n        private readonly region: string,\n        /** Full Azure voice name (e.g. 'de-DE-KatjaNeural'); empty → pick by language. */\n        private readonly voice: string,\n    ) {}\n\n    async synthesize(text: string, lang: string): Promise<TtsResult> {\n        const speechConfig = sdk.SpeechConfig.fromSubscription(this.key, this.region);\n        speechConfig.speechSynthesisOutputFormat = sdk.SpeechSynthesisOutputFormat.Raw24Khz16BitMonoPcm;\n        if (this.voice) {\n            speechConfig.speechSynthesisVoiceName = this.voice;\n        } else {\n            speechConfig.speechSynthesisLanguage = isoToLocale(lang);\n        }\n\n        // audioConfig=null → synthesise to memory only, no default-speaker output.\n        const synth = new sdk.SpeechSynthesizer(speechConfig, null);\n        try {\n            const result = await new Promise<sdk.SpeechSynthesisResult>((resolve, reject) => {\n                synth.speakTextAsync(text, resolve, reject);\n            });\n            if (result.reason === sdk.ResultReason.SynthesizingAudioCompleted) {\n                return { pcm: Buffer.from(result.audioData), sampleRate: 24000 };\n            }\n            throw new Error(`Azure TTS failed: ${result.errorDetails || result.reason}`);\n        } finally {\n            synth.close();\n        }\n    }\n}\n"]}