wingbot 3.77.0-alpha.0 → 3.77.0-alpha.2

package/.claude/settings.local.json

@@ -0,0 +1,11 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npx mocha:*)",
+      "Bash(npx tsc *)",
+      "Bash(npm test *)",
+      "Bash(node -e \"const p = require\\('./bot/plugins/BTMLLM'\\); console.log\\('factory type:', typeof p\\); console.log\\('factory name:', p.name\\);\")",
+      "Bash(grep -n \"prompt\\\\`\\\\|tagged\\\\|render\\\\|compile\\\\|hbs\" /Users/ondrejveres/Wingbot/wingbot-llm/src/prompt.js)"
+    ]
+  }
+}

package/index.js

@@ -70,6 +70,7 @@ const LLM = require('./src/LLM');
 const LLMSession = require('./src/LLMSession');
 const LLMTool = require('./src/LLMTool');
 const LLMType = require('./src/LLMType');
+const LLMToolRunner = require('./src/LLMToolRunner');
 const LLMRouter = require('./src/LLMRouter');
 const prompt = require('./src/prompt');
 
@@ -167,6 +168,7 @@ module.exports = {
     LLMSession,
     LLMTool,
     LLMType,
+    LLMToolRunner,
 
     LLMRouter,
     prompt

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wingbot",
-  "version": "3.77.0-alpha.0",
+  "version": "3.77.0-alpha.2",
   "description": "Enterprise Messaging Bot Conversation Engine",
   "main": "index.js",
   "type": "commonjs",

package/src/ChatGpt.js

@@ -450,8 +450,10 @@ class ChatGpt {
                 ...(requestTokens ? {
                     max_completion_tokens: requestTokens
                 } : {}),
+                // Chat Completions takes "reasoning_effort" ("reasoning: { effort }" is the
+                // Responses API - here 400 Unknown parameter)
                 ...(reasoningEffort ? {
-                    reasoning: { effort: reasoningEffort }
+                    reasoning_effort: reasoningEffort
                 } : {}),
                 ...(typeof parallelToolCalls === 'boolean' ? {
                     parallel_tool_calls: parallelToolCalls

package/src/LLMSession.js

@@ -101,6 +101,7 @@ const stateData = require('./utils/stateData');
 /**
  * @callback ToolFnCallback
  * @param {{[key: string]: any}} input
+ * @param {LLMSession} [session] - call `session.stop()` to end the generation after the tool
  * @returns {string|Promise<string>}
  */
 
@@ -256,6 +257,8 @@ class LLMSession {
 
         /** @type {PossiblyAsyncContent|null} */
         this._fallbackMessage = null;
+
+        this._stopped = false;
     }
 
     /**
@@ -374,6 +377,15 @@ class LLMSession {
             .then(onFulfilled, onRejected);
     }
 
+    /**
+     * the preset (or the provider options), the session generates with by default
+     *
+     * @returns {string|object}
+     */
+    get preset () {
+        return this._preset;
+    }
+
     /**
      * @returns {ToolFunction[]}
      */
@@ -903,6 +915,28 @@ class LLMSession {
         return this;
     }
 
+    /**
+     * Ends the generation right after the current round of tool calls - the model
+     * is not asked again and nothing generated in this session is sent.
+     *
+     * Meant to be called from within a tool, which takes over the conversation
+     * (e.g. makes a postback to an interaction). It's applied immediately
+     * (not queued), because the tool already runs inside a queued job.
+     *
+     * @returns {this}
+     */
+    stop () {
+        this._stopped = true;
+        return this;
+    }
+
+    /**
+     * @returns {boolean}
+     */
+    isStoppedSync () {
+        return this._stopped;
+    }
+
     /**
      * @returns {Promise<string>}
      */
@@ -1024,6 +1058,16 @@ class LLMSession {
                     },
                     ...results.filter((r) => !!r)
                 );
+            }
+
+            if (this._stopped) {
+                // a tool took over the conversation - drop any text generated
+                // alongside the tool calls and don't ask the model again
+                result = { role: ROLE_ASSISTANT, content: null };
+                break;
+            }
+
+            if (toolCalls.length) {
                 result = await this._llm.generate(this, providerOptions, logOptions);
             } else {
                 // everything failed - force a final text answer without tools
@@ -1093,7 +1137,7 @@ class LLMSession {
         let args;
         try {
             args = JSON.parse(toolCall.args);
-            const fnResult = await Promise.resolve(tool.fn(args));
+            const fnResult = await Promise.resolve(tool.fn(args, this));
 
             /**
              * {
@@ -1193,6 +1237,9 @@ class LLMSession {
      */
     send (quickReplies = undefined) {
         this._job(() => {
+            if (this._stopped) {
+                return;
+            }
             const messages = this.messagesToSendSync();
             this._onSend(messages, quickReplies);
         }, true);

package/src/LLMToolRunner.js

@@ -0,0 +1,580 @@
+/**
+ * @author Ondrej Veres
+ */
+'use strict';
+
+const LLMType = require('./LLMType');
+const compileWithState = require('./utils/compileWithState');
+const stateData = require('./utils/stateData');
+const getCondition = require('./utils/getCondition');
+const { compare, ConditionOperators } = require('./utils/customCondition');
+const { getValue } = require('./utils/getUpdate');
+
+/** @typedef {import('./Request')} Request */
+/** @typedef {import('./Responder')} Responder */
+/** @typedef {import('./Plugins')} Plugins */
+/** @typedef {import('./LLMSession')} LLMSession */
+/** @typedef {import('./Responder').QuickReply} QuickReply */
+
+/**
+ * texts in languages as the designer exports them ([{ l, t }], as the multilang inputs),
+ * or { [lang]: text }
+ *
+ * @typedef {{ l: string|null, t: string }[]|{ [lang: string]: string }} ToolTexts
+ */
+
+/**
+ * @typedef {object} ToolParameterDefinition
+ * @prop {string} name
+ * @prop {'string'|'number'|'boolean'|'enum'|'array'} type
+ * @prop {boolean} [optional]
+ * @prop {string} [description]
+ * @prop {{ value: string, description: string }[]} [values]
+ * @prop {ToolParameterDefinition[]} [items] - array: fields of the objects in the array
+ */
+
+/**
+ * A button of a situation - a prefilled call of a tool (or just a text the user sends)
+ *
+ * @typedef {object} ToolButtonDefinition
+ * @prop {ToolTexts} title
+ * @prop {string|null} tool - the tool the click calls (null - the title goes to the LLM as a text)
+ * @prop {object|null} [args] - arguments of the tool, strings can use the values
+ *   of the situation ("{{botCounterOffer}}" keeps the number)
+ * @prop {boolean} [hasCondition] - the condition (as the conditions of the designer):
+ *   the variables are the values of the situation and the state
+ * @prop {boolean} [hasEditableCondition]
+ * @prop {any[][]} [editableCondition]
+ * @prop {string} [conditionFn]
+ */
+
+/**
+ * What happens in a situation - the designer sets either the instruction for the LLM
+ * (the conversation with the LLM continues), or the target (a postback)
+ *
+ * @typedef {object} ToolSituationDefinition
+ * @prop {ToolTexts} [instruction]
+ * @prop {string|null} [action] - target interaction
+ * @prop {object} [setState] - set before the postback to the target
+ *   (strings can use the values of the situation)
+ * @prop {ToolButtonDefinition[]} [buttons] - offered with the answer of the LLM
+ */
+
+/**
+ * Tool as it comes from the designer (Tools tab, on the root block of the snapshot)
+ *
+ * @typedef {object} ToolDefinition
+ * @prop {string} id
+ * @prop {string} description
+ * @prop {ToolParameterDefinition[]} [parameters]
+ * @prop {{ [id: string]: ToolSituationDefinition }} [situations]
+ */
+
+/**
+ * What a tool (registered with plugins.registerTool()) returns - the situation, the code
+ * found out. What follows (an instruction for the LLM, or a target) is set in the designer.
+ *
+ * @typedef {object} ToolResult
+ * @prop {string} situation - id of the situation
+ * @prop {object} [data] - values for the texts, the set state and the buttons
+ * @prop {string} [asTool] - the situation is defined on another tool
+ *   (e.g. a refusal, which turned out to be a repeated offer)
+ */
+
+/**
+ * @typedef {object} LLMToolRunnerOptions
+ * @prop {object[]} [blocks] - blocks of the snapshot (the tools are on the root block)
+ * @prop {Plugins} [plugins] - code of the tools (plugins.registerTool())
+ * @prop {Console} [log]
+ * @prop {boolean} [allowForbiddenSnippetWords] - for the code conditions of the buttons
+ *   (as in the bot)
+ * @prop {string} [source] - for the logs and the tracking (e.g. "prompt", "mainLoop")
+ */
+
+/**
+ * @param {ToolTexts} texts
+ * @param {string} lang
+ * @returns {string}
+ */
+function textForLang (texts, lang) {
+    if (!texts) {
+        return '';
+    }
+    // a text can have alternatives (["Accept", "Take it"]) - the first filled one is used
+    const first = (t) => (Array.isArray(t) ? t.find((a) => `${a || ''}`.trim()) || '' : t || '');
+    const byLang = Array.isArray(texts)
+        ? Object.fromEntries(texts.map((tr) => [tr.l || '', first(tr.t)]))
+        : Object.fromEntries(Object.entries(texts).map(([l, t]) => [l, first(t)]));
+    if (lang && `${byLang[lang] || ''}`.trim()) {
+        return byLang[lang];
+    }
+    return byLang.en || Object.values(byLang).find((t) => `${t || ''}`.trim()) || '';
+}
+
+/**
+ * @param {ToolParameterDefinition} param
+ * @returns {LLMType}
+ */
+function parameterType (param) {
+    let type;
+    let { description } = param;
+
+    switch (param.type) {
+        case 'number':
+            type = LLMType.number();
+            break;
+        case 'boolean':
+            type = LLMType.boolean();
+            break;
+        case 'enum':
+            type = LLMType.enum(param.values.map((v) => v.value));
+            description = [
+                description,
+                ...param.values
+                    .filter((v) => v.description)
+                    .map((v) => `- ${v.value}: ${v.description}`)
+            ].filter((d) => !!d).join('\n');
+            break;
+        case 'array':
+            // array of objects - the fields are parameters too
+            type = LLMType.array(LLMType.object(Object.fromEntries(
+                (param.items || []).map((item) => [item.name, parameterType(item)])
+            )));
+            break;
+        default:
+            type = LLMType.string();
+    }
+
+    if (description) {
+        type.description(description);
+    }
+    return param.optional ? type.optional() : type;
+}
+
+/**
+ * @param {ToolDefinition} def
+ * @returns {LLMType}
+ */
+function parametersType (def) {
+    return LLMType.object(Object.fromEntries(
+        (def.parameters || []).map((param) => [param.name, parameterType(param)])
+    ));
+}
+
+// a template, which is just one value - "{{price}}"
+const SINGLE_VALUE = /^\{\{\s*([a-zA-Z0-9_$]+)\s*\}\}$/;
+
+// the click of a button of a situation - in the data of the quick reply
+const BUTTON_KEY = '_llmToolButton';
+
+/**
+ * @param {string} template
+ * @param {(template: string) => string} compile
+ * @param {object} values
+ * @returns {any}
+ */
+function compileValue (template, compile, values) {
+    const single = template.trim().match(SINGLE_VALUE);
+    if (single && Object.prototype.hasOwnProperty.call(values, single[1])) {
+        return values[single[1]];
+    }
+    return compile(template);
+}
+
+/**
+ * Set state from the designer - texts are filled with the values of the situation now
+ * (the values won't be in the state later), special values (increment, entity, ...)
+ * are kept. A template with just one value keeps its type ("{{price}}" stays a number).
+ *
+ * @param {object} setState
+ * @param {(template: string) => string} compile
+ * @param {object} [values]
+ * @returns {object}
+ */
+function quickReplySetState (setState, compile, values = {}) {
+    return Object.fromEntries(
+        Object.entries(setState || {})
+            .map(([key, value]) => [
+                key,
+                typeof value === 'string' ? compileValue(value, compile, values) : value
+            ])
+    );
+}
+
+/**
+ * Arguments of a tool for a button - every string can use the values of the situation,
+ * a template with just one value keeps its type
+ *
+ * @param {any} args
+ * @param {(template: string) => string} compile
+ * @param {object} [values]
+ * @returns {any}
+ */
+function compileArgs (args, compile, values = {}) {
+    if (typeof args === 'string') {
+        return compileValue(args, compile, values);
+    }
+    if (Array.isArray(args)) {
+        return args.map((a) => compileArgs(a, compile, values));
+    }
+    if (args && typeof args === 'object') {
+        return Object.fromEntries(Object.entries(args)
+            .map(([key, value]) => [key, compileArgs(value, compile, values)]));
+    }
+    return args;
+}
+
+/**
+ * Runs the tools placed in the interactions ("LLM Tool" blocks the request passed)
+ * within an LLM session, which talks to the user:
+ *
+ * - the LLM calls a tool by what the user did, the code of the tool
+ *   (plugins.registerTool()) returns the situation
+ * - what follows is in the designer (Tools tab): the instruction for the LLM
+ *   with the buttons, or the target interaction (a postback)
+ * - a button is a prefilled call of a tool - the click runs the same code
+ *   as when the user writes it (handleButton())
+ */
+class LLMToolRunner {
+
+    /**
+     * @param {Request} req
+     * @param {Responder} res
+     * @param {LLMToolRunnerOptions} [options]
+     */
+    constructor (req, res, options = {}) {
+        const {
+            blocks = [], plugins = null, log = console, source = 'llm',
+            allowForbiddenSnippetWords = false
+        } = options;
+
+        this._req = req;
+        this._res = res;
+        this._plugins = plugins;
+        this._log = log;
+        this._source = source;
+        this._allowForbiddenSnippetWords = allowForbiddenSnippetWords;
+
+        const rootBlock = (blocks || []).find((b) => b && b.isRoot);
+
+        /** @type {ToolDefinition[]} */
+        this._definitions = (rootBlock && rootBlock.tools) || [];
+
+        /** @type {Map<string, (args: object, session: LLMSession) => Promise<string>>} */
+        this._attached = new Map();
+
+        /** @type {string|null} */
+        this.postBackAction = null;
+
+        /** @type {QuickReply[]} */
+        this.quickReplies = [];
+
+        /** number of tools attached to the session */
+        this.count = 0;
+    }
+
+    /**
+     * the current state - with the changes of the tools (e.g. a new language
+     * is used for the texts right after the tool switched it)
+     *
+     * @returns {object}
+     */
+    _stateData () {
+        return stateData(this._req, this._res);
+    }
+
+    /**
+     * @param {string} template
+     * @param {object} [values]
+     * @returns {string}
+     */
+    _compile (template, values = {}) {
+        return compileWithState(this._req, this._res, template, {
+            ...this._stateData(),
+            ...values
+        });
+    }
+
+    /**
+     * @param {string} action
+     * @param {LLMSession} session
+     * @returns {string}
+     */
+    _makePostBack (action, session) {
+        if (this.postBackAction) {
+            return 'Ignored - the conversation already continues elsewhere.';
+        }
+        this.postBackAction = action;
+        session.stop();
+        return 'OK';
+    }
+
+    /**
+     * @param {ToolDefinition} def
+     * @param {string} situation
+     * @param {object} values
+     * @returns {string}
+     */
+    _instructionText (def, situation, values) {
+        const { lang } = this._stateData();
+        const sit = (def.situations || {})[situation] || {};
+        const template = textForLang(sit.instruction, lang);
+
+        if (!template) {
+            this._log.error(`LLM tool "${def.id}" - situation "${situation}" has no instruction in the designer`);
+            return `${situation}: ${JSON.stringify(values)}`;
+        }
+        return this._compile(template, values);
+    }
+
+    /**
+     * The condition of the button - over the values of the situation and the state
+     *
+     * @param {ToolDefinition} def
+     * @param {ToolButtonDefinition} button
+     * @param {object} values
+     * @returns {boolean}
+     */
+    _buttonShown (def, button, values) {
+        if (!button.hasCondition) {
+            return true;
+        }
+        try {
+            if (!button.hasEditableCondition) {
+                // a code condition - (req, res, values)
+                const fn = getCondition(button, {
+                    configuration: this._req.configuration,
+                    allowForbiddenSnippetWords: this._allowForbiddenSnippetWords
+                }, `LLM tool "${def.id}" button`);
+                const shown = fn(this._req, this._res, values);
+                if (shown && typeof shown.then === 'function') {
+                    // the buttons are made synchronously - an async condition can't be used
+                    throw new Error('the condition must not be async');
+                }
+                return !!shown;
+            }
+            const data = { ...this._stateData(), ...values };
+            const raw = [
+                ConditionOperators['matches regexp'],
+                ConditionOperators['not matches regexp'],
+                ConditionOperators['is true'],
+                ConditionOperators['is false']
+            ];
+            return (button.editableCondition || []).some((list) => list.every((cond) => compare(
+                getValue(cond.variable, data),
+                cond.operator,
+                raw.includes(cond.operator) ? cond.value : this._compile(cond.value, values)
+            )));
+        } catch (e) {
+            this._log.error(`LLM tool "${def.id}" - invalid condition of a button: ${e.message}`, e);
+            return false;
+        }
+    }
+
+    /**
+     * The buttons of the situation - with the answer of the LLM
+     *
+     * @param {ToolDefinition} def
+     * @param {string} situation
+     * @param {object} values
+     */
+    _addButtons (def, situation, values) {
+        const sit = (def.situations || {})[situation] || {};
+        const { lang } = this._stateData();
+        const compile = (t) => this._compile(t, values);
+        const action = this._res.currentAction();
+
+        (sit.buttons || [])
+            .filter((button) => this._buttonShown(def, button, values))
+            .forEach((button) => {
+                const title = compile(textForLang(button.title, lang)).trim();
+
+                if (!title) {
+                    this._log.error(`LLM tool "${def.id}" - a button of "${situation}" has no title in the designer`);
+                    return;
+                }
+                this.quickReplies.push({
+                    action,
+                    title,
+                    ...(button.tool && {
+                        data: {
+                            [BUTTON_KEY]: {
+                                tool: button.tool,
+                                args: compileArgs(button.args || {}, compile, values)
+                            }
+                        }
+                    })
+                });
+            });
+    }
+
+    /**
+     * Runs the code of the tool and what follows the situation
+     *
+     * @param {ToolDefinition} def
+     * @param {Function} fn
+     * @param {object} args
+     * @param {LLMSession} session
+     * @returns {Promise<string>}
+     */
+    async _runTool (def, fn, args, session) {
+        const { _req: req, _res: res } = this;
+
+        /** @type {ToolResult} */
+        const result = await fn(args, req, res, session);
+
+        if (!result || !result.situation) {
+            // no situation - the result goes to the LLM as it is (as in LLMSession)
+            if (result === undefined || result === null) {
+                return 'OK';
+            }
+            return typeof result === 'string' ? result : JSON.stringify(result);
+        }
+
+        const { situation, data: values = {} } = result;
+        res.trackEvent('tool', this._source, def.id, situation);
+
+        const sitDef = result.asTool
+            ? this._definitions.find((d) => d.id === result.asTool) || def
+            : def;
+        const sit = (sitDef.situations || {})[situation];
+
+        if (!sit) {
+            this._log.error(`LLM tool "${def.id}" - situation "${situation}" is not in the designer (tools.json)`);
+        }
+
+        if (sit && sit.action) {
+            if (this.postBackAction) {
+                // another tool has already moved the conversation - its state stays
+                return this._makePostBack(sit.action, session);
+            }
+            // the conversation continues in the target interaction
+            const setState = quickReplySetState(
+                sit.setState,
+                (t) => this._compile(t, values),
+                values
+            );
+            if (Object.keys(setState).length) {
+                res.setState(setState);
+            }
+            return this._makePostBack(sit.action, session);
+        }
+
+        // only the buttons of the last situation are offered (the earlier ones are outdated)
+        this.quickReplies = [];
+        this._addButtons(sitDef, situation, values);
+        return this._instructionText(sitDef, situation, values);
+    }
+
+    /**
+     * Adds the tools placed in the interactions, the request passed, to the session
+     *
+     * @param {LLMSession} session
+     * @returns {this}
+     */
+    attach (session) {
+        this._res.llmTools()
+            .map((id) => {
+                const def = this._definitions.find((d) => d.id === id);
+                if (!def) {
+                    this._log.error(`LLM tool "${id}" is placed in an interaction, but it's not in the Tools tab`);
+                }
+                return def;
+            })
+            .filter((def) => !!def)
+            .forEach((def) => {
+                const fn = this._plugins && this._plugins.getTool(def.id);
+
+                if (!fn) {
+                    this._log.error(`LLM tool "${def.id}" is in the designer, but it's not registered in the code`);
+                    return;
+                }
+
+                const run = (args, s) => this._runTool(def, fn, args, s);
+                this._attached.set(def.id, run);
+                this.count += 1;
+                session.tool({
+                    name: def.id,
+                    description: def.description,
+                    parameters: parametersType(def),
+                    fn: run
+                });
+            });
+
+        return this;
+    }
+
+    /**
+     * The click of a button of a situation - calls its tool the same way, as when
+     * the LLM calls it (the call is in the conversation for the LLM).
+     * Then generate the answer - unless the situation made a postback (postBackAction).
+     *
+     * Only the tools placed on the way can be called (the data of the click come
+     * from the user - the same as writing it).
+     *
+     * @param {LLMSession} session
+     * @returns {Promise<boolean>} - a button was clicked
+     */
+    async handleButton (session) {
+        const button = this._req.actionData()[BUTTON_KEY];
+
+        if (!button || typeof button.tool !== 'string') {
+            return false;
+        }
+
+        const run = this._attached.get(button.tool);
+        if (!run) {
+            this._log.error(`LLM tool "${button.tool}" of a button is not placed on the way to the interaction`);
+            return false;
+        }
+
+        const args = button.args && typeof button.args === 'object' ? button.args : {};
+        const id = `button_${button.tool}`;
+        let content;
+        try {
+            content = await run(args, session);
+        } catch (e) {
+            // the same as a failed call of the LLM - not in the conversation, the LLM answers
+            this._log.error(`LLM tool "${button.tool}" of a button: ${e.message}`, e, { args });
+            return false;
+        }
+
+        session.push(
+            {
+                role: 'assistant',
+                toolCalls: [{
+                    id, type: 'function', name: button.tool, args: JSON.stringify(args)
+                }]
+            },
+            { role: 'tool', content, toolCallId: id }
+        );
+        return true;
+    }
+
+    /**
+     * Provider options for the generation - one tool call at a time, when there are tools
+     * (the tools change the state - e.g. two offers in one message would both be recorded)
+     *
+     * @param {LLMSession} session
+     * @returns {string|object}
+     */
+    generateOptions (session) {
+        const { preset } = session;
+        if (this.count === 0) {
+            return preset;
+        }
+        return {
+            ...(typeof preset === 'string' || !preset ? { preset } : preset),
+            parallelToolCalls: false
+        };
+    }
+}
+
+LLMToolRunner.BUTTON_KEY = BUTTON_KEY;
+LLMToolRunner.textForLang = textForLang;
+LLMToolRunner.parameterType = parameterType;
+LLMToolRunner.parametersType = parametersType;
+LLMToolRunner.quickReplySetState = quickReplySetState;
+LLMToolRunner.compileArgs = compileArgs;
+
+module.exports = LLMToolRunner;

package/src/Plugins.js

@@ -46,6 +46,20 @@ const { compileWithState } = require('./utils');
  * @prop {string[]} [notLastMessageItems]
  */
 
+/**
+ * Tool, which can be offered to the LLM - its description and parameters are
+ * defined in the designer (tools.json)
+ *
+ * @template {object} [S=object]
+ * @template {BaseConfiguration} [C=object]
+ * @callback PluginTool
+ * @param {object} args - arguments filled by the LLM
+ * @param {Request<S,C>} req
+ * @param {Responder} res
+ * @param {import('./LLMSession')} session
+ * @returns {any|Promise<any>}
+ */
+
 /**
  * Custom code plugins for BuildRouter and wingbot.ai
  *
@@ -57,6 +71,9 @@ class Plugins {
 
     constructor () {
         this._plugins = new Map();
+
+        /** @type {Map<string,PluginTool<S,C>>} */
+        this._tools = new Map();
     }
 
     /**
@@ -214,6 +231,10 @@ class Plugins {
         name._plugins.forEach((el, key) => {
             this._plugins.set(key, el);
         });
+        // a plugins object of an older wingbot has no tools
+        (name._tools || new Map()).forEach((el, key) => {
+            this._tools.set(key, el);
+        });
     }
 
     /**
@@ -231,6 +252,38 @@ class Plugins {
         this._plugins.set(name, { pluginFactory, options });
     }
 
+    /**
+     * Register tool for the LLM
+     *
+     * @param {string} id - tool id (has to match the id in tools.json)
+     * @param {PluginTool<S,C>} tool
+     */
+    registerTool (id, tool) {
+        if (typeof tool !== 'function') {
+            throw new Error(`Tool should be a function, ${typeof tool} given (tool: ${id})`);
+        }
+        this._tools.set(id, tool);
+    }
+
+    /**
+     * Get registered tool
+     *
+     * @param {string} id
+     * @returns {PluginTool<S,C>|null}
+     */
+    getTool (id) {
+        return this._tools.get(id) || null;
+    }
+
+    /**
+     * Ids of all registered tools
+     *
+     * @returns {string[]}
+     */
+    getToolIds () {
+        return Array.from(this._tools.keys());
+    }
+
 }
 
 module.exports = Plugins;

package/src/Responder.js

@@ -253,6 +253,9 @@ class Responder {
 
         /** @typedef {PromptSource|Promise<string>} PromptContextItem */
 
+        /** @type {Set<string>} - ids of the tools placed in the interactions, the request passed */
+        this._llmTools = new Set();
+
         /** @type {Map<string,PromptContextItem[]>} */
         this._llmContext = new Map([
             [this.LLM_CTX_DEFAULT, []],
@@ -301,6 +304,28 @@ class Responder {
         return this;
     }
 
+    /**
+     * Makes a tool (registered with plugins.registerTool()) available to the LLM,
+     * which talks to the user in this request (prompt messages, plugins using LLMToolRunner)
+     * - like the instructions, the tools are collected on the way to the interaction
+     *
+     * @param {string} toolId
+     * @returns {this}
+     */
+    llmAddTool (toolId) {
+        this._llmTools.add(toolId);
+        return this;
+    }
+
+    /**
+     * Ids of the tools added in this request (in the order they were added)
+     *
+     * @returns {string[]}
+     */
+    llmTools () {
+        return [...this._llmTools];
+    }
+
     /**
      *
      * @param {LLMFilter|LLMFilterFn} filter

package/src/log/types.js

@@ -59,7 +59,70 @@
  * @returns {void}
  */
 
-/** @typedef {<T>(name: string, fn: () => T|Promise<T>, attrs?: object) => Promise<T>} SpanFn */
+/**
+ * The role of a span (OpenTelemetry SpanKind). App Insights picks the table
+ * by it: `server` and `consumer` are AppRequests (the start of an operation:
+ * an HTTP request, a worker run taken from a timer or a queue), the others are
+ * AppDependencies (`client`: a call to another system, `internal`: a step).
+ *
+ * @typedef {'internal'|'server'|'client'|'producer'|'consumer'} SpanKindName
+ */
+
+/**
+ * @typedef {object} SpanOptions
+ * @prop {SpanKindName} [kind] default `internal`
+ */
+
+/**
+ * @typedef {<T>(
+ *  name: string, fn: () => T|Promise<T>, attrs?: object, options?: SpanOptions
+ * ) => Promise<T>} SpanFn
+ */
+
+/**
+ * A call to another system (SAP, Microsoft Graph, KSRM ...), see `log.httpCall()`.
+ *
+ * @typedef {object} HttpCall
+ * @prop {string} [method] `GET`, `POST` ...
+ * @prop {string|null} [url] the full URL (query secrets are redacted)
+ * @prop {Record<string, any>} [params] the small values that tell what the
+ *  call is about (query parameters, ids, type, language)
+ * @prop {Record<string, any>|null} [headers] the request headers, when
+ *  `send()` is not axios (axios: the headers it sent are read from the
+ *  response); secret headers are redacted
+ * @prop {any} [body] the request body (redacted, cut at 8000 characters)
+ * @prop {Record<string, any>} [data] more fields of the row (ECS
+ *  `eventAction` ...)
+ */
+
+/**
+ * What `toResponse` reads; what it leaves out is read like an axios response
+ * (`status`, `data`, `headers`, `config.headers`).
+ *
+ * @typedef {object} HttpCallResponse
+ * @prop {number|null} [status] the HTTP status
+ * @prop {any} [body] the response body
+ * @prop {Record<string, any>|null} [headers] the response headers
+ * @prop {Record<string, any>|null} [requestHeaders] the headers that were sent
+ */
+
+/**
+ * @template R
+ * @typedef {object} HttpCallOptions
+ * @prop {(res: R) => HttpCallResponse} [toResponse] reads the status, the body
+ *  and the headers of what `send()` returns (and of `error.response`), or
+ *  changes the body for the log
+ */
+
+/**
+ * `httpCall(name, send, call, options)`, like `span(name, fn, data, options)`.
+ * The name is the span name and the message of the row, a constant per
+ * operation: `SAP getListVA`, `Graph sendMail` (not the URL, it has ids).
+ *
+ * @typedef {<R>(
+ *  name: string, send: () => Promise<R>, call?: HttpCall, options?: HttpCallOptions<R>
+ * ) => Promise<R>} HttpCallFn
+ */
 
 /**
  * What a library needs from a logger: the five levels. `console`, the shared

package/src/resolvers/index.js

@@ -18,11 +18,13 @@ const setState = require('./setState');
 const expectedInput = require('./expectedInput');
 const skip = require('./skip');
 const contextMessage = require('./contextMessage');
+const llmTool = require('./llmTool');
 
 module.exports = {
     path,
     message,
     contextMessage,
+    llmTool,
     include,
     postback,
     expected,

package/src/resolvers/llmTool.js

@@ -0,0 +1,41 @@
+/*
+ * @author Ondrej Veres
+ */
+'use strict';
+
+const Router = require('../Router');
+const getCondition = require('../utils/getCondition');
+
+/** @typedef {import('../BuildRouter').BotContext<any>} BotContext */
+/** @typedef {import('../Router').Resolver<any>} Resolver */
+/** @typedef {import('../utils/getCondition').ConditionDefinition} ConditionDefinition */
+
+/**
+ * @typedef {object} LlmToolParamsBase
+ * @property {string} toolId - id of a tool registered with plugins.registerTool()
+ */
+
+/** @typedef {LlmToolParamsBase & ConditionDefinition} LlmToolParams */
+
+/**
+ * Makes a tool available to the LLM, which talks to the user - like the instructions
+ * (contextMessage), it's collected on the way to the interaction
+ * (in the root - everywhere, in a dialog - only there)
+ *
+ * @param {LlmToolParams} params
+ * @param {BotContext} context
+ * @returns {Resolver}
+ */
+function llmTool (params, context) {
+    const { toolId } = params;
+    const condition = getCondition(params, context, `LLM tool "${toolId}"`);
+
+    return async (req, res) => {
+        if (toolId && await condition(req, res)) {
+            res.llmAddTool(toolId);
+        }
+        return Router.CONTINUE;
+    };
+}
+
+module.exports = llmTool;

package/src/resolvers/message.js

@@ -22,6 +22,7 @@ const {
 const { vars, VAR_TYPES } = require('../utils/stateVariables');
 const LLM = require('../LLM');
 const canaryLog = require('../utils/canaryLog');
+const LLMToolRunner = require('../LLMToolRunner');
 
 /** @typedef {import('../Responder').VoiceControl} VoiceControl */
 /** @typedef {import('../BuildRouter').LinksMap} LinksMap */
@@ -317,9 +318,10 @@ function selectTranslation (resolverId, params, texts, data) {
  * @param {"message" | "prompt"} [params.type]
  * @param {string} [params.llmContextType]
  * @param {BotContext} context
+ * @param {import('../Plugins')} [plugins] - code of the LLM tools placed in the interactions
  * @returns {Resolver}
  */
-function message (params, context = {}) {
+function message (params, context = {}, plugins = null) {
     const {
         // @ts-ignore
         isLastIndex, isLastMessage, linksMap, configuration, resolverId
@@ -459,10 +461,36 @@ function message (params, context = {}) {
             let discard;
             let llmError;
 
+            // the tools placed on the way to this interaction ("LLM Tool" blocks)
+            const tools = new LLMToolRunner(req, res, {
+                // @ts-ignore
+                blocks: context.blocks,
+                plugins,
+                log: context.log,
+                allowForbiddenSnippetWords: context.allowForbiddenSnippetWords,
+                source: 'prompt'
+            });
+
             try {
                 session = res.llmSessionWithHistory(params.llmContextType);
-                await session.systemPrompt(text)
-                    .generate();
+                tools.attach(session);
+                // a button of a tool - its tool runs the same way, as when the LLM calls it
+                await tools.handleButton(session);
+                if (!tools.postBackAction && !session.isStoppedSync()) {
+                    await session.systemPrompt(text)
+                        .generate(tools.generateOptions(session));
+                }
+
+                if (tools.postBackAction) {
+                    // a situation with a target - the conversation continues in its interaction
+                    postBack(tools.postBackAction);
+                    return Router.END;
+                }
+
+                if (session.isStoppedSync()) {
+                    // a tool took over the conversation (session.stop()) - nothing more is sent
+                    return Router.END;
+                }
 
                 evaluation = await res.llmEvaluate(session, params.llmContextType);
                 ({ discard } = evaluation);
@@ -503,6 +531,11 @@ function message (params, context = {}) {
 
                 res.setFlag(LLM.GPT_FLAG);
 
+                if (tools.quickReplies.length) {
+                    // quick replies of the tools go with the answer of the LLM
+                    sendReplies = [...(sendReplies || []), ...tools.quickReplies];
+                }
+
                 const lastMessageI = messages.length - 1;
                 messages.forEach((m, i) => {
                     if (lastMessageI === i) {