iobroker.javascript 10.2.5 → 10.4.0

package/build/main.js

@@ -4,7 +4,7 @@
  *
  * The MIT License (MIT)
  *
- * Copyright (c) 2014-2024 bluefox <dogafox@gmail.com>,
+ * Copyright (c) 2014-2026 bluefox <dogafox@gmail.com>,
  *
  * Copyright (c) 2014      hobbyquaker
  */
@@ -81,6 +81,7 @@ const sandbox_1 = require("./lib/sandbox");
 const nodeModulesManagement_1 = require("./lib/nodeModulesManagement");
 const secrets_1 = require("./lib/secrets");
 const aiProviderResolver_1 = require("./lib/aiProviderResolver");
+const scriptHistory_1 = require("./lib/scriptHistory");
 const anthropicAdapter_1 = require("./lib/anthropicAdapter");
 const eventObj_1 = require("./lib/eventObj");
 const scheduler_1 = require("./lib/scheduler");
@@ -107,6 +108,11 @@ const forbiddenMirrorLocations = [
 ];
 const packageJson = JSON.parse((0, node_fs_1.readFileSync)(`${__dirname}/../package.json`).toString());
 const SCRIPT_CODE_MARKER = 'script.js.';
+/**
+ * Instance-message type the script editor subscribes to, and under which finished AI answers are
+ * pushed back to it. Shared verbatim with `src-editor/src/AiChat/AiChatService.ts`.
+ */
+const AI_PUSH_MESSAGE_TYPE = 'aiChatAnswer';
 let webstormDebug;
 const isCI = !!process.env.CI;
 // ambient declarations for typescript
@@ -241,6 +247,8 @@ const TS_MEMORY_RELEASE_DELAY_MS = 60_000;
  * gone and the type definitions and compilers are given back.
  */
 const EDITOR_ONLINE_TIMEOUT_MS = 30_000;
+/** An editor showing a function block diagram online asks every 10 s; after this, it is gone */
+const FBD_WATCH_TIMEOUT_MS = 30_000;
 /** How often it is checked whether the editor has gone away */
 const EDITOR_CHECK_INTERVAL_MS = 10_000;
 // compiler instance for global JS declarations. Built on the first compilation only - see LazyTsServer
@@ -344,6 +352,13 @@ class JavaScript extends adapter_core_1.Adapter {
      * subscriptions set up in `subscribeAiCredentials`.
      */
     aiCredentialCache = new Map();
+    /**
+     * Editor sessions waiting for pushed AI answers: the session token the editor invented when it
+     * subscribed, mapped to the client id the messaging controller gave us. A `chatCompletion`
+     * message carries the token, which is how a request is matched back to the browser tab that
+     * sent it - the message itself has no socket id.
+     */
+    aiUiClients = new Map();
     /** Unsubscribe callbacks for the AI credential subscriptions (manager mode). */
     aiCredentialUnsubscribers = [];
     /**
@@ -368,6 +383,8 @@ class JavaScript extends adapter_core_1.Adapter {
     typingPackageFiles = [];
     /** Until when a script editor counts as open. Refreshed by every `editorPing` */
     editorOnlineUntil = 0;
+    /** Counts the editors that started to show a function block diagram online - see `fbdWatch` */
+    fbdViewers = 0;
     /** Checks regularly whether the editor is gone and the type definitions can be unloaded */
     editorCheckInterval = null;
     /** Set once the user has been told that TypeScript is compiled without type definitions */
@@ -387,6 +404,16 @@ class JavaScript extends adapter_core_1.Adapter {
             ...options,
             name: 'javascript', // adapter name
             useFormatDate: true,
+            /*
+             * The script editor subscribes here so that a finished AI answer can be *pushed* to it.
+             * An AI request regularly runs longer than 30 s, and `@iobroker/ws` answers every socket
+             * callback with the string "timeout" after exactly that (socket.io.js: `Date.now() + 30_000`,
+             * not configurable). The answer then arrived in a dead callback and the chat stayed empty
+             * with nothing in any log. So the editor gets an immediate acknowledgement and the result
+             * later as an instance message.
+             */
+            uiClientSubscribe: (info) => this.onUiClientSubscribe(info),
+            uiClientUnsubscribe: (info) => this.onUiClientUnsubscribe(info),
             /**
              * If the JS-Controller catches an unhandled error, this will be called,
              * so we have a chance to handle it ourselves.
@@ -468,6 +495,13 @@ class JavaScript extends adapter_core_1.Adapter {
                 }
             }
         }
+        if (debugMode) {
+            // This process was started by the inspector (see `debugStart`) with `--debug`, so the whole log goes
+            // through the pipes of that process. If it is gone, writing to them fails with EPIPE, and an unhandled
+            // EPIPE would end the debugged process with an uncaught exception (#2382)
+            process.stdout.on('error', () => { });
+            process.stderr.on('error', () => { });
+        }
         this.context = {
             mods: this.mods,
             objects: this.objects,
@@ -502,6 +536,9 @@ class JavaScript extends adapter_core_1.Adapter {
             scheduler: null,
             timerId: 0,
             rulesOpened: null, // opened rules
+            fbdWatch: new Map(),
+            fbdDebug: new Map(),
+            fbdDebugSettings: new Map(),
             language: this.language || 'en',
             updateLogSubscriptions: this.updateLogSubscriptions.bind(this),
             convertBackStringifiedValues: this.convertBackStringifiedValues.bind(this),
@@ -516,6 +553,220 @@ class JavaScript extends adapter_core_1.Adapter {
         };
         this.tsServer = new lazyTsServer_1.LazyTsServer(typescriptSettings_1.tsCompilerOptions, this.tsLog, TS_MEMORY_RELEASE_DELAY_MS);
     }
+    /**
+     * Make sure the instance has a file area, which is where the script history lives.
+     *
+     * The adapter's own namespace needs a `meta` object before anything can be written under it.
+     * Deliberately not `javascript.admin`: that is the UI's file area and every
+     * `iobroker upload javascript` wipes it.
+     */
+    async ensureHistoryStorage() {
+        try {
+            await this.setForeignObjectNotExistsAsync(this.namespace, {
+                type: 'meta',
+                common: {
+                    name: 'javascript files',
+                    type: 'meta.user',
+                },
+                native: {},
+            });
+        }
+        catch (e) {
+            this.log.warn(`Cannot create the file storage of the instance: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    /**
+     * Keep the saved source of a script, so it can be looked at and brought back later.
+     *
+     * Hooked into the object change and not into the editor on purpose: this way a change from the
+     * mirror directory, from the object browser, from another script or from the AI is kept just
+     * the same as one typed into the editor.
+     *
+     * @param id id of the script
+     * @param obj the script as it is now
+     * @param formerObj the script as it was before this change, if it existed
+     */
+    async storeScriptVersion(id, obj, formerObj) {
+        const keep = (0, scriptHistory_1.resolveHistoryVersions)(this.config.historyVersions);
+        if (!keep) {
+            return;
+        }
+        // Only the instance that runs the script writes its history, otherwise two instances
+        // store every version twice
+        if (obj.common?.engine !== `system.adapter.${this.namespace}`) {
+            return;
+        }
+        const source = obj.common.source;
+        if (!(0, scriptHistory_1.isWorthStoring)(formerObj?.common?.source, source)) {
+            return;
+        }
+        try {
+            const ts = typeof obj.ts === 'number' && obj.ts ? obj.ts : Date.now();
+            const entry = {
+                ts,
+                ...(obj.from ? { from: obj.from } : {}),
+                ...(obj.user ? { user: obj.user } : {}),
+                // The source of a protected script is encrypted in the object and is kept that
+                // way - the history must not be the place where it lies around in plain text
+                ...(0, scriptHistory_1.describeSource)(source, !!obj.native?.protected),
+            };
+            await this.writeFileAsync(this.namespace, (0, scriptHistory_1.versionPath)(id, ts), source);
+            const raw = await this.readFileAsync(this.namespace, (0, scriptHistory_1.indexPath)(id)).catch(() => null);
+            const current = (0, scriptHistory_1.parseIndex)((0, scriptHistory_1.fileToString)(raw));
+            const { index, obsolete } = (0, scriptHistory_1.addVersion)(current, entry, keep);
+            await this.writeFileAsync(this.namespace, (0, scriptHistory_1.indexPath)(id), JSON.stringify(index));
+            for (const old of obsolete) {
+                await this.delFileAsync(this.namespace, (0, scriptHistory_1.versionPath)(id, old)).catch(() => {
+                    /* a version that is already gone is one we do not have to delete */
+                });
+            }
+            this.log.debug(`Script history: stored version ${ts} of ${id} (${index.length} kept)`);
+        }
+        catch (e) {
+            // A history is a convenience; it must never get in the way of saving a script
+            this.log.warn(`Cannot store the version of ${id}: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    /**
+     * The stored versions of a script, newest first, without their sources.
+     *
+     * @param id id of the script
+     */
+    async readScriptVersions(id) {
+        try {
+            const raw = await this.readFileAsync(this.namespace, (0, scriptHistory_1.indexPath)(id));
+            return (0, scriptHistory_1.parseIndex)((0, scriptHistory_1.fileToString)(raw));
+        }
+        catch {
+            // No history yet - not an error, just nothing to show
+            return [];
+        }
+    }
+    /** What every stored history occupies, biggest first - read from the indexes, never from the sources */
+    async collectHistoryUsage() {
+        const rows = [];
+        let folders = [];
+        try {
+            folders = await this.readDirAsync(this.namespace, scriptHistory_1.HISTORY_ROOT);
+        }
+        catch {
+            // Nothing stored yet
+        }
+        for (const folder of folders) {
+            const id = (0, scriptHistory_1.decodeFolderName)(folder.file);
+            const index = await this.readScriptVersions(id);
+            if (!index.length) {
+                continue;
+            }
+            const { versions, bytes } = (0, scriptHistory_1.sumIndex)(index);
+            rows.push({ id, exists: !!this.objects[id], versions, bytes });
+        }
+        rows.sort((a, b) => b.bytes - a.bytes);
+        return {
+            rows,
+            total: {
+                scripts: rows.length,
+                versions: rows.reduce((sum, r) => sum + r.versions, 0),
+                bytes: rows.reduce((sum, r) => sum + r.bytes, 0),
+            },
+        };
+    }
+    /**
+     * Remove stored versions.
+     *
+     * @param options what to remove
+     * @param options.id the script whose versions are meant
+     * @param options.ts one single version of that script; without it the whole history goes
+     * @param options.orphans every history whose script no longer exists
+     * @param options.all every stored version there is - the scripts themselves stay untouched
+     */
+    async deleteHistory(options) {
+        let deleted = 0;
+        let bytes = 0;
+        /**
+         * Delete versions of one script and write the remaining index back.
+         *
+         * @param id the script
+         * @param keep the versions that stay; an empty list removes the index as well
+         * @param drop the versions to remove
+         */
+        const apply = async (id, keep, drop) => {
+            for (const version of drop) {
+                bytes += version.size || 0;
+                deleted++;
+                await this.delFileAsync(this.namespace, (0, scriptHistory_1.versionPath)(id, version.ts)).catch(() => {
+                    /* a version that is already gone is one we do not have to delete */
+                });
+            }
+            if (keep.length) {
+                await this.writeFileAsync(this.namespace, (0, scriptHistory_1.indexPath)(id), JSON.stringify(keep));
+            }
+            else {
+                await this.delFileAsync(this.namespace, (0, scriptHistory_1.indexPath)(id)).catch(() => {
+                    /* already gone */
+                });
+            }
+        };
+        if (options.orphans || options.all) {
+            const { rows } = await this.collectHistoryUsage();
+            // `all` takes everything, `orphans` only what has no script behind it anymore
+            for (const row of options.all ? rows : rows.filter(r => !r.exists)) {
+                await apply(row.id, [], await this.readScriptVersions(row.id));
+            }
+        }
+        else if (options.id) {
+            const index = await this.readScriptVersions(options.id);
+            if (options.ts) {
+                await apply(options.id, index.filter(v => v.ts !== options.ts), index.filter(v => v.ts === options.ts));
+            }
+            else {
+                await apply(options.id, [], index);
+            }
+        }
+        this.log.debug(`Script history: removed ${deleted} versions (${(0, scriptHistory_1.formatBytes)(bytes)})`);
+        return { deleted, bytes };
+    }
+    /**
+     * Cut every history down to the configured number of versions.
+     *
+     * Without this a smaller limit would only take effect script by script, on the next save of
+     * each - and setting it to zero would never free anything at all.
+     */
+    async trimAllHistories() {
+        const keep = (0, scriptHistory_1.resolveHistoryVersions)(this.config.historyVersions);
+        let folders = [];
+        try {
+            folders = await this.readDirAsync(this.namespace, scriptHistory_1.HISTORY_ROOT);
+        }
+        catch {
+            return;
+        }
+        for (const folder of folders) {
+            const id = (0, scriptHistory_1.decodeFolderName)(folder.file);
+            const index = await this.readScriptVersions(id);
+            if (!index.length) {
+                continue;
+            }
+            const { index: kept, obsolete } = (0, scriptHistory_1.trimIndex)(index, keep);
+            if (!obsolete.length) {
+                continue;
+            }
+            for (const ts of obsolete) {
+                await this.delFileAsync(this.namespace, (0, scriptHistory_1.versionPath)(id, ts)).catch(() => {
+                    /* already gone */
+                });
+            }
+            if (kept.length) {
+                await this.writeFileAsync(this.namespace, (0, scriptHistory_1.indexPath)(id), JSON.stringify(kept));
+            }
+            else {
+                await this.delFileAsync(this.namespace, (0, scriptHistory_1.indexPath)(id)).catch(() => {
+                    /* already gone */
+                });
+            }
+            this.log.debug(`Script history: trimmed ${id} to ${kept.length} versions`);
+        }
+    }
     async onObjectChange(id, obj) {
         // Check if we should ignore this change (once!) because we just updated the compiled sources
         if (this.ignoreObjectChange.has(id)) {
@@ -605,6 +856,10 @@ class JavaScript extends adapter_core_1.Adapter {
                 }
             }
         }
+        // Keep the saved source before the branches below decide what else to do with it
+        if (obj?.type === 'script') {
+            await this.storeScriptVersion(id, obj, formerObj);
+        }
         // handle Script object updates
         if (!obj && formerObj?.type === 'script') {
             // Object Deleted just now
@@ -814,7 +1069,9 @@ class JavaScript extends adapter_core_1.Adapter {
     }
     async onUnload(callback) {
         try {
-            await this.debugStop();
+            // Do not wait for it: the inspector needs a moment to stop the debugged process, and it does that by
+            // itself as soon as the connection to this process is gone. The shutdown must not be delayed by it.
+            void this.debugStop();
             this.stopTimeSchedules();
             if (this.setStateCountCheckInterval) {
                 clearInterval(this.setStateCountCheckInterval);
@@ -877,6 +1134,79 @@ class JavaScript extends adapter_core_1.Adapter {
         }
         await this.main();
     }
+    /**
+     * A script editor registers itself for pushed AI answers.
+     *
+     * The editor sends a token it made up; we remember which messaging-controller client it belongs
+     * to. Only our own message type is accepted - anything else is some other UI asking for
+     * something we do not serve.
+     *
+     * @param info client id and the subscribe message, as the messaging controller hands it over
+     * @param info.clientId the id to address this client with later
+     * @param info.message the subscribe message, carrying the type and the editor's session token
+     */
+    onUiClientSubscribe(info) {
+        const message = info.message?.message;
+        if (message?.type !== AI_PUSH_MESSAGE_TYPE) {
+            return { accepted: false, error: `Unknown subscription type "${message?.type || ''}"` };
+        }
+        const token = (message.data?.sessionToken || '').trim();
+        if (!token) {
+            return { accepted: false, error: 'No session token provided' };
+        }
+        this.aiUiClients.set(token, info.clientId);
+        this.log.debug(`AI editor session subscribed for pushed answers (${this.aiUiClients.size} open)`);
+        return { accepted: true };
+    }
+    /**
+     * A script editor went away - drop every token that pointed at it.
+     *
+     * @param info the client the messaging controller is retiring
+     * @param info.clientId the id that is going away
+     */
+    onUiClientUnsubscribe(info) {
+        for (const [token, clientId] of this.aiUiClients) {
+            if (clientId === info.clientId) {
+                this.aiUiClients.delete(token);
+            }
+        }
+        this.log.debug(`AI editor session unsubscribed (${this.aiUiClients.size} open)`);
+    }
+    /**
+     * Build the function that delivers the answer of one `chatCompletion` request.
+     *
+     * If the editor registered for pushed answers and named itself in the message, the answer goes
+     * out as an instance message and the socket callback is acknowledged right away. Everything
+     * else - an older editor, the inline completion, a script calling us - keeps the plain
+     * request/response behaviour.
+     *
+     * @param obj the incoming sendTo message
+     */
+    buildAiResponder(obj) {
+        const token = (obj.message?.uiSession || '').toString().trim();
+        const requestId = (obj.message?.requestId || '').toString().trim();
+        const clientId = token ? this.aiUiClients.get(token) : undefined;
+        if (!clientId || !requestId) {
+            return payload => this.sendTo(obj.from, obj.command, payload, obj.callback);
+        }
+        // Release the socket callback immediately - it has 30 s to live, the request has more.
+        this.sendTo(obj.from, obj.command, { accepted: true, requestId }, obj.callback);
+        let sent = false;
+        return payload => {
+            if (sent) {
+                return;
+            }
+            sent = true;
+            this.sendToUI({
+                clientId,
+                data: { type: AI_PUSH_MESSAGE_TYPE, requestId, ...payload },
+            }).catch(e => {
+                // The tab was closed, or the admin dropped the subscription in the meantime.
+                this.aiUiClients.delete(token);
+                this.log.warn(`Cannot deliver the AI answer to the editor: ${e instanceof Error ? e.message : String(e)}`);
+            });
+        };
+    }
     /** Read and decrypt a single AI credential's key from the central store; returns '' (and logs) on error. */
     async readAiCredentialKey(id) {
         if (!adapter_core_1.Credentials?.getCredentials) {
@@ -885,6 +1215,15 @@ class JavaScript extends adapter_core_1.Adapter {
         }
         try {
             const cred = await adapter_core_1.Credentials.getCredentials(this, id);
+            /*
+             * Only an entry that was stored as an AI credential. The store holds the secrets of the
+             * whole system - a database password, the login of a camera - and nothing but this check
+             * keeps a request for "the key of this provider" from reaching one of them.
+             */
+            if (cred?.type !== 'ai') {
+                this.log.warn(`Cannot read AI credential "${id}": it is not an AI credential`);
+                return '';
+            }
             return (cred?.values?.key || '').trim();
         }
         catch (e) {
@@ -904,12 +1243,12 @@ class JavaScript extends adapter_core_1.Adapter {
      * The settings-dialog Test button may pass form values that are not saved yet
      * (`messageApiKey` / `messageCredentialId` / `credentialType`); those win over the stored config.
      */
-    async resolveAiCredentials(provider, opts = {}) {
-        const mode = opts.credentialType || this.config.credentialType || 'manual';
+    async resolveAiCredentials(provider) {
+        const mode = this.config.credentialType || 'manual';
         if (mode === 'manager') {
             // The base URL is not a secret and is resolved the same way in both modes.
-            const { baseUrl } = (0, aiProviderResolver_1.resolveProviderCredentials)(this.config, provider, opts.messageBaseUrl);
-            const id = (opts.messageCredentialId || (0, aiProviderResolver_1.getProviderCredentialId)(this.config, provider)).trim();
+            const { baseUrl } = (0, aiProviderResolver_1.resolveProviderCredentials)(this.config, provider);
+            const id = (0, aiProviderResolver_1.getProviderCredentialId)(this.config, provider).trim();
             if (!id) {
                 return { apiKey: '', baseUrl };
             }
@@ -918,11 +1257,74 @@ class JavaScript extends adapter_core_1.Adapter {
             const apiKey = cached !== undefined ? cached : await this.readAiCredentialKey(id);
             return { apiKey, baseUrl };
         }
+        return (0, aiProviderResolver_1.resolveProviderCredentials)(this.config, provider);
+    }
+    /**
+     * Endpoint and key for the Test button of the settings dialog.
+     *
+     * The dialog tries what stands in the form - a key that was typed but not saved, a credential that
+     * was chosen but not saved, an endpoint that was entered but not saved. What the form may decide is
+     * limited by `resolveTestEndpoint`: a secret of this system is never carried to an address that
+     * came with the message. A chat request takes none of this and reads the configuration instead -
+     * see `resolveAiCredentials`.
+     *
+     * @param provider the provider that is being tested
+     * @param opts what the Test button sent
+     * @param opts.messageBaseUrl the address that stands in the form
+     * @param opts.messageApiKey the key that stands in the form
+     * @param opts.messageCredentialId the entry of the credential store that the form names
+     * @param opts.credentialType where the form says the keys are kept
+     */
+    async resolveAiTestCredentials(provider, opts = {}) {
+        const mode = opts.credentialType || this.config.credentialType || 'manual';
+        if (mode === 'manager') {
+            // A key out of the store is a secret of this system, so the address is the stored one
+            const { baseUrl } = (0, aiProviderResolver_1.resolveProviderCredentials)(this.config, provider);
+            const id = (opts.messageCredentialId || (0, aiProviderResolver_1.getProviderCredentialId)(this.config, provider)).trim();
+            if (!id) {
+                return { apiKey: '', baseUrl };
+            }
+            const cached = this.aiCredentialCache.get(id);
+            const apiKey = cached !== undefined ? cached : await this.readAiCredentialKey(id);
+            return { apiKey, baseUrl };
+        }
         // Manual mode. The Test button sends the current form key (maybe empty) — let it win.
         if (opts.messageApiKey !== undefined) {
             return (0, aiProviderResolver_1.resolveTestCredentials)(this.config, provider, opts.messageApiKey, opts.messageBaseUrl);
         }
-        return (0, aiProviderResolver_1.resolveProviderCredentials)(this.config, provider, opts.messageBaseUrl);
+        return (0, aiProviderResolver_1.resolveProviderCredentials)(this.config, provider);
+    }
+    /**
+     * Whether the user a message was sent on behalf of may have code executed here.
+     *
+     * `obj.user` arrives with js-controller 7.2.5 and newer: a socket server such as `admin` or `web`
+     * puts the authenticated user of the connection there, and a socket client cannot set it itself.
+     * Where it is missing - an older controller, a script, an adapter that names nobody - nothing is
+     * checked and everything stays as it was.
+     *
+     * The right asked for is the one `cmdExec` is checked against: running a script here is running
+     * code on this host, whatever the ACL of the single objects it then touches says.
+     *
+     * @param obj the incoming message
+     */
+    async mayExecuteFor(obj) {
+        // `user` is not in the older `@iobroker/types` this adapter builds against
+        const user = obj.user;
+        if (!user) {
+            return null;
+        }
+        try {
+            const permissions = await this.calculatePermissionsAsync(user, {
+                cmdExec: { type: 'other', operation: 'execute' },
+            });
+            if (permissions?.other?.execute) {
+                return null;
+            }
+            return `User "${user}" has no permission to execute scripts`;
+        }
+        catch (e) {
+            return `Cannot check the permissions of "${user}": ${e instanceof Error ? e.message : String(e)}`;
+        }
     }
     /**
      * Warns about the one setup that the fix for #2369 stops working.
@@ -1199,12 +1601,154 @@ class JavaScript extends adapter_core_1.Adapter {
                 console.log(`Enable messaging for ${this.context.rulesOpened}`);
                 break;
             }
+            case 'fbdWatch': {
+                // An editor shows a function block diagram online. While it keeps asking, the runtime
+                // of the script sends snapshots to `debug.fbd`; a window that just goes away is
+                // forgotten after FBD_WATCH_TIMEOUT_MS. `full`: a new viewer, who needs everything once.
+                // `path`: the instance of a user block whose inside the editor shows, like `b3/b7`.
+                const { script, watch, full, path } = (obj.message || {});
+                if (typeof script === 'string') {
+                    if (watch) {
+                        const current = this.context.fbdWatch.get(script);
+                        const until = Date.now() + FBD_WATCH_TIMEOUT_MS;
+                        // several editors may look into several instances
+                        const paths = current?.paths || new Map();
+                        if (typeof path === 'string' && path) {
+                            paths.set(path, until);
+                        }
+                        this.context.fbdWatch.set(script, {
+                            until,
+                            viewer: !current || full ? ++this.fbdViewers : current.viewer,
+                            paths,
+                        });
+                    }
+                    else {
+                        this.context.fbdWatch.delete(script);
+                    }
+                }
+                if (obj.callback) {
+                    this.sendTo(obj.from, obj.command, { ok: true }, obj.callback);
+                }
+                break;
+            }
+            case 'fbdDebug': {
+                // The online view forces values, sets breakpoints or steps through a diagram. The
+                // runtime of the script does it and answers with how it stands now.
+                const { script, ...command } = (obj.message || {});
+                const handler = typeof script === 'string' ? this.context.fbdDebug.get(script) : undefined;
+                let result;
+                if (!handler) {
+                    result = { error: 'The diagram does not run' };
+                }
+                else if (!this.context.fbdWatch.has(script)) {
+                    // everything the online view sets ends with it
+                    result = { error: 'The diagram is not shown online' };
+                }
+                else {
+                    try {
+                        result = { status: handler(command) };
+                    }
+                    catch (error) {
+                        result = { error: error.message };
+                    }
+                }
+                if (obj.callback) {
+                    this.sendTo(obj.from, obj.command, result, obj.callback);
+                }
+                break;
+            }
             case 'rulesOff': {
                 // maybe if (context.rulesOpened === obj.message)
                 console.log(`Disable messaging for ${this.context.rulesOpened}`);
                 this.context.rulesOpened = null;
                 break;
             }
+            case 'getScriptVersions': {
+                // The stored versions of one script, without their sources - the list must stay
+                // cheap, a history of 30 Blockly versions is megabytes
+                void (async () => {
+                    if (!obj.callback) {
+                        return;
+                    }
+                    const scriptId = (obj.message?.id || '').toString();
+                    if (!scriptId) {
+                        this.sendTo(obj.from, obj.command, { error: 'No script ID provided' }, obj.callback);
+                        return;
+                    }
+                    const versions = await this.readScriptVersions(scriptId);
+                    this.sendTo(obj.from, obj.command, { versions }, obj.callback);
+                })();
+                break;
+            }
+            case 'getScriptVersion': {
+                // The source of one stored version, fetched when it is actually looked at
+                void (async () => {
+                    if (!obj.callback) {
+                        return;
+                    }
+                    const scriptId = (obj.message?.id || '').toString();
+                    const ts = parseInt(obj.message?.ts, 10);
+                    if (!scriptId || isNaN(ts)) {
+                        this.sendTo(obj.from, obj.command, { error: 'No script ID or timestamp' }, obj.callback);
+                        return;
+                    }
+                    try {
+                        const raw = await this.readFileAsync(this.namespace, (0, scriptHistory_1.versionPath)(scriptId, ts));
+                        const source = (0, scriptHistory_1.fileToString)(raw);
+                        this.sendTo(obj.from, obj.command, { source }, obj.callback);
+                    }
+                    catch (e) {
+                        this.sendTo(obj.from, obj.command, { error: `Cannot read the version: ${e instanceof Error ? e.message : String(e)}` }, obj.callback);
+                    }
+                })();
+                break;
+            }
+            case 'getHistoryUsage': {
+                // Read by the overview in the adapter settings (`textSendTo` with container html)
+                void (async () => {
+                    if (!obj.callback) {
+                        return;
+                    }
+                    try {
+                        this.sendTo(obj.from, obj.command, await this.collectHistoryUsage(), obj.callback);
+                    }
+                    catch (e) {
+                        this.sendTo(obj.from, obj.command, { error: `Cannot read the history: ${e instanceof Error ? e.message : String(e)}` }, obj.callback);
+                    }
+                })();
+                break;
+            }
+            case 'deleteHistory': {
+                // One version, the history of one script, or every history without a script
+                void (async () => {
+                    if (!obj.callback) {
+                        return;
+                    }
+                    const scriptId = (obj.message?.id || '').toString();
+                    const orphans = !!obj.message?.orphans;
+                    // Wiping every history is a deliberate request, never the default of a
+                    // message that forgot to say what it meant
+                    const all = !!obj.message?.all;
+                    if (!scriptId && !orphans && !all) {
+                        this.sendTo(obj.from, obj.command, { error: 'No script ID provided' }, obj.callback);
+                        return;
+                    }
+                    try {
+                        const ts = parseInt(obj.message?.ts, 10);
+                        const result = await this.deleteHistory({
+                            ...(scriptId ? { id: scriptId } : {}),
+                            ...(isNaN(ts) ? {} : { ts }),
+                            ...(orphans ? { orphans: true } : {}),
+                            ...(all ? { all: true } : {}),
+                        });
+                        this.sendTo(obj.from, obj.command, result, obj.callback);
+                    }
+                    catch (e) {
+                        this.sendTo(obj.from, obj.command, { error: `Cannot delete: ${e instanceof Error ? e.message : String(e)}` }, obj.callback);
+                    }
+                })();
+                break;
+            }
             case 'getIoBrokerDataDir': {
                 if (obj.callback) {
                     this.sendTo(obj.from, obj.command, {
@@ -1220,25 +1764,33 @@ class JavaScript extends adapter_core_1.Adapter {
                 // credentials manager — they never leave the adapter (frontend only sends `provider`).
                 void (async () => {
                     if (!obj.callback) {
+                        this.log.warn(`chatCompletion from ${obj.from} came without a callback - nobody can receive the answer`);
                         return;
                     }
                     const chatModel = (obj.message?.model || '').trim();
                     const messages = obj.message?.messages;
                     const tools = obj.message?.tools;
                     const provider = (obj.message?.provider || 'openai').trim();
+                    // One line per request, so an empty chat panel can be told apart from a request
+                    // that never arrived here. Without it the log stays silent either way.
+                    this.log.debug(`chatCompletion from ${obj.from}: ${provider}/${chatModel}, ${Array.isArray(messages) ? messages.length : 0} messages, ${Array.isArray(tools) ? tools.length : 0} tools`);
+                    // Answers go through this from here on: either straight back through the socket
+                    // callback, or - for an editor that registered for it - pushed as an instance
+                    // message once the endpoint is done. See `buildAiResponder`.
+                    const respond = this.buildAiResponder(obj);
                     // How long the caller is willing to wait - see `resolveRequestTimeout`
                     const requestTimeout = (0, aiProviderResolver_1.resolveRequestTimeout)(obj.message?.timeout);
-                    const { apiKey, baseUrl } = await this.resolveAiCredentials(provider, {
-                        messageBaseUrl: obj.message?.baseUrl,
-                    });
+                    const maxTokens = (0, aiProviderResolver_1.resolveMaxTokens)(this.config.aiMaxTokens);
+                    // Endpoint and key come from the configuration; a request cannot name either
+                    const { apiKey, baseUrl } = await this.resolveAiCredentials(provider);
                     // Anthropic, Gemini, and DeepSeek always require an API key; OpenAI-compatible allows empty key with custom base URL
                     if (!apiKey &&
                         (provider === 'anthropic' || provider === 'gemini' || provider === 'deepseek' || !baseUrl)) {
-                        this.sendTo(obj.from, obj.command, { error: 'No API key provided' }, obj.callback);
+                        respond({ error: 'No API key provided' });
                         return;
                     }
                     if (!chatModel || !messages) {
-                        this.sendTo(obj.from, obj.command, { error: 'Model and messages are required' }, obj.callback);
+                        respond({ error: 'Model and messages are required' });
                         return;
                     }
                     let url;
@@ -1255,7 +1807,15 @@ class JavaScript extends adapter_core_1.Adapter {
                         const anthropicTools = tools?.length ? (0, anthropicAdapter_1.translateToolsToAnthropic)(tools) : [];
                         bodyObj = {
                             model: chatModel,
-                            max_tokens: 8192,
+                            /*
+                             * Anthropic requires `max_tokens`, so unlike the other providers it
+                             * cannot be left to the endpoint. 8192 is the default because it is
+                             * what every Anthropic model accepts - the older small ones cap out
+                             * below that and answer 400 to anything higher. The newer models write
+                             * far longer answers than that, and a script that runs into the limit
+                             * is simply cut off mid-line, so the value is a setting.
+                             */
+                            max_tokens: maxTokens,
                             stream: false,
                             ...(systemText ? { system: systemText } : {}),
                             messages: anthropicMessages,
@@ -1301,7 +1861,7 @@ class JavaScript extends adapter_core_1.Adapter {
                     chatHeaders['Content-Length'] = bodyBuffer.length;
                     const resolved = resolveRequestModule(url);
                     if (!resolved) {
-                        this.sendTo(obj.from, obj.command, { error: `Invalid API URL: ${url}` }, obj.callback);
+                        respond({ error: `Invalid API URL: ${url}` });
                         return;
                     }
                     const { module: requestModule, isHttps } = resolved;
@@ -1332,19 +1892,39 @@ class JavaScript extends adapter_core_1.Adapter {
                                             content = message?.content || '';
                                             tool_calls = message?.tool_calls;
                                         }
-                                        if (!content && !tool_calls?.length) {
-                                            this.sendTo(obj.from, obj.command, { error: 'Empty response from API' }, obj.callback);
+                                        // How the endpoint says it finished. Passed on in both
+                                        // cases, so the editor can tell a truncated answer from
+                                        // a complete one instead of just showing what arrived.
+                                        const info = (0, aiProviderResolver_1.extractAiResponseInfo)(parsed);
+                                        // `.trim()`, because a whitespace-only answer is just as
+                                        // empty to the user but used to slip past this check and
+                                        // arrive in the editor as a blank chat bubble with no
+                                        // reason attached - the stop reason below is the whole point.
+                                        if (!content.trim() && !tool_calls?.length) {
+                                            const error = (0, aiProviderResolver_1.describeEmptyAiResponse)(info, data);
+                                            // What arrived instead of an answer. Without this the
+                                            // log only repeats what is already known - that there
+                                            // is nothing - instead of naming the blocks that came
+                                            const shape = provider === 'anthropic'
+                                                ? (0, anthropicAdapter_1.describeAnthropicContent)(parsed)
+                                                : `choices: ${parsed.choices?.length ?? 0}, content: ${typeof parsed
+                                                    .choices?.[0]?.message?.content}`;
+                                            this.log.warn(`chatCompletion (${provider}/${chatModel}): ${error}. Answer contained: ${shape}`);
+                                            respond({ error, ...info });
                                         }
                                         else {
-                                            this.sendTo(obj.from, obj.command, {
+                                            this.log.debug(`chatCompletion (${provider}/${chatModel}): answered with ${content.length} characters, ${tool_calls?.length || 0} tool calls, stop reason ${info.finishReason || '-'}`);
+                                            respond({
                                                 success: true,
                                                 content,
                                                 ...(tool_calls ? { tool_calls } : {}),
-                                            }, obj.callback);
+                                                ...info,
+                                            });
                                         }
                                     }
-                                    catch {
-                                        this.sendTo(obj.from, obj.command, { error: 'Invalid JSON response from API' }, obj.callback);
+                                    catch (e) {
+                                        this.log.warn(`chatCompletion (${provider}/${chatModel}): cannot read the answer of ${url}: ${e instanceof Error ? e.message : String(e)}. Response: ${data.substring(0, 200)}`);
+                                        respond({ error: 'Invalid JSON response from API' });
                                     }
                                 }
                                 else {
@@ -1356,24 +1936,28 @@ class JavaScript extends adapter_core_1.Adapter {
                                     catch {
                                         detail = data.substring(0, 200);
                                     }
-                                    this.sendTo(obj.from, obj.command, {
-                                        error: `${detail || httpStatusText(res.statusCode || 0)} (${res.statusCode})`,
-                                    }, obj.callback);
+                                    const error = `${detail || httpStatusText(res.statusCode || 0)} (${res.statusCode})`;
+                                    this.log.warn(`chatCompletion (${provider}/${chatModel}): ${error}`);
+                                    respond({ error });
                                 }
                             });
                         });
                         req.on('error', (err) => {
-                            this.sendTo(obj.from, obj.command, { error: `Connection failed: ${err.message}` }, obj.callback);
+                            this.log.warn(`chatCompletion (${provider}/${chatModel}): cannot reach ${url}: ${err.message}`);
+                            respond({ error: `Connection failed: ${err.message}` });
                         });
                         req.on('timeout', () => {
                             req.destroy();
-                            this.sendTo(obj.from, obj.command, { error: `Connection timeout (${Math.round(requestTimeout / 1000)}s)` }, obj.callback);
+                            const error = `Connection timeout (${Math.round(requestTimeout / 1000)}s)`;
+                            this.log.warn(`chatCompletion (${provider}/${chatModel}): ${url} - ${error}`);
+                            respond({ error });
                         });
                         req.write(bodyBuffer);
                         req.end();
                     }
                     catch (error) {
-                        this.sendTo(obj.from, obj.command, { error: `Connection failed: ${error.toString()}` }, obj.callback);
+                        this.log.warn(`chatCompletion (${provider}/${chatModel}): ${url} - ${error.toString()}`);
+                        respond({ error: `Connection failed: ${error.toString()}` });
                     }
                 })();
                 break;
@@ -1387,7 +1971,7 @@ class JavaScript extends adapter_core_1.Adapter {
                         return;
                     }
                     const provider = (obj.message?.provider || 'openai').trim();
-                    const { apiKey, baseUrl } = await this.resolveAiCredentials(provider, {
+                    const { apiKey, baseUrl } = await this.resolveAiTestCredentials(provider, {
                         messageApiKey: obj.message?.apiKey,
                         messageBaseUrl: obj.message?.baseUrl,
                         messageCredentialId: obj.message?.credentialId,
@@ -1396,7 +1980,17 @@ class JavaScript extends adapter_core_1.Adapter {
                     // Anthropic, Gemini, and DeepSeek always require an API key; OpenAI-compatible allows empty key with custom base URL
                     if (!apiKey &&
                         (provider === 'anthropic' || provider === 'gemini' || provider === 'deepseek' || !baseUrl)) {
-                        this.sendTo(obj.from, obj.command, { error: 'No API key provided' }, obj.callback);
+                        // Say which of the two setups came up empty - "No API key provided" sent the user
+                        // looking for a key field that `manager` mode does not even show.
+                        const mode = obj.message?.credentialType || this.config.credentialType || 'manual';
+                        let error = 'No API key provided';
+                        if (mode === 'manager') {
+                            const id = (obj.message?.credentialId || (0, aiProviderResolver_1.getProviderCredentialId)(this.config, provider)).trim();
+                            error = id
+                                ? `Credential "${id}" contains no API key`
+                                : `No credential selected for "${provider}"`;
+                        }
+                        this.sendTo(obj.from, obj.command, { error }, obj.callback);
                         return;
                     }
                     let url;
@@ -1555,7 +2149,15 @@ class JavaScript extends adapter_core_1.Adapter {
             }
             case 'execute': {
                 if (obj.callback) {
-                    void this.executeScript(obj.message)
+                    /*
+                     * This runs code on this host with the whole ioBroker API behind it. Anybody who
+                     * may send a message here could ask for it, and the message never said on whose
+                     * behalf - so there was nothing to check it against. Where the controller names
+                     * the user (js-controller 7.2.5 and newer), that user needs the right a command on
+                     * the host needs; where it does not, nothing changes.
+                     */
+                    void this.mayExecuteFor(obj)
+                        .then(async (error) => error ? { ok: false, error, logs: [], output: '' } : await this.executeScript(obj.message))
                         .then(result => this.sendTo(obj.from, obj.command, result, obj.callback))
                         .catch(err => this.sendTo(obj.from, obj.command, {
                         ok: false,
@@ -1627,6 +2229,9 @@ class JavaScript extends adapter_core_1.Adapter {
         }
     }
     async main() {
+        await this.ensureHistoryStorage();
+        // Makes a changed limit take effect at once instead of script by script
+        await this.trimAllHistories();
         // Patch the font as it sometimes is wrong
         if (!this.context.debugMode) {
             if (await this.patchFont()) {
@@ -3057,7 +3662,9 @@ class JavaScript extends adapter_core_1.Adapter {
             obj.common.engineType ||= '';
             if (obj.common.engineType.toLowerCase().startsWith('javascript') ||
                 obj.common.engineType === 'Blockly' ||
-                obj.common.engineType === 'Rules') {
+                obj.common.engineType === 'Rules' ||
+                // function block diagram: generated JavaScript, like Blockly and Rules (not known to @iobroker/types yet)
+                obj.common.engineType === 'FBD') {
                 // Javascript
                 this.log.info(`${name}: start JavaScript (${obj.common.engineType})`);
                 let sourceFn = name;
@@ -3488,10 +4095,12 @@ class JavaScript extends adapter_core_1.Adapter {
     async debugStop() {
         if (this.debugState.child) {
             this.debugSendToInspector({ cmd: 'end' });
+            // The inspector stops the debugged process first and ends itself only then, because that process writes
+            // its log through its pipes (#2382). Kill it only if it does not manage that in time.
             this.debugState.endTimeout = setTimeout(() => {
                 this.debugState.endTimeout = null;
-                this.debugState.child?.kill('SIGTERM');
-            }, 500);
+                this.debugState.child?.kill('SIGKILL');
+            }, 5_000);
             this.debugState.promiseOnEnd ||= Promise.resolve(0);
         }
         else {