wingbot 3.76.17 → 3.77.0-alpha.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wingbot",
-  "version": "3.76.17",
+  "version": "3.77.0-alpha.0",
   "description": "Enterprise Messaging Bot Conversation Engine",
   "main": "index.js",
   "type": "commonjs",
@@ -75,7 +75,7 @@
   },
   "optionalDependencies": {
     "axios": "^1.6.4",
-    "handlebars": "^4.0.0"
+    "handlebars": "4.7.10"
   },
   "allowScripts": {
     "fsevents@2.3.2": true,

package/src/BuildRouter.js

@@ -157,12 +157,7 @@ const DUMMY_ROUTE = { id: 0, path: null, resolvers: [] };
  * @returns {string}
 */
 
-/**
- * @typedef {object} ILogger
- * @prop {Function} log
- * @prop {Function} warn
- * @prop {Function} error
- */
+/** @typedef {import('./log/types').LevelLogger} ILogger */
 
 /**
  * @template {BaseConfiguration} [C=object]
@@ -206,11 +201,7 @@ const DUMMY_ROUTE = { id: 0, path: null, resolvers: [] };
  * @prop {string|number} [resolverId] - only for text messages with random characters
  */
 
-/**
- * @typedef {object} Logger
- * @prop {Function} log
- * @prop {Function} error
- */
+/** @typedef {import('./log/types').LevelLogger} Logger */
 
 /**
  * @typedef {object} RunningReq
@@ -400,6 +391,30 @@ class BuildRouter extends Router {
         return this._botLoaded;
     }
 
+    /**
+     * What an expired request was about, without the whole request and
+     * responder (they hold the state and the transcript).
+     *
+     * @param {any[]} args - the reduce() arguments: (req, res, ...)
+     * @param {number} timeoutMs
+     * @returns {object}
+     */
+    static _expireInfo (args, timeoutMs) {
+        const [req] = Array.isArray(args) ? args : [];
+        let action = null;
+        try {
+            action = req && typeof req.action === 'function' ? req.action() : null;
+        } catch (e) {
+            // the action is only a hint
+        }
+        return {
+            senderId: (req && req.senderId) || null,
+            pageId: (req && req.pageId) || null,
+            action,
+            timeoutMs
+        };
+    }
+
     async reduce (...args) {
         await this.preload();
 
@@ -411,7 +426,7 @@ class BuildRouter extends Router {
             const timeoutPromise = new Promise((resolve) => {
                 timeout = setTimeout(() => {
                     timeout = null;
-                    this._logger.error('BuildRouter EXPIRE', { args });
+                    this._logger.error('BuildRouter EXPIRE', BuildRouter._expireInfo(args, this.runningReqTimeout));
                     this._runningReqs = this._runningReqs
                         .filter((rr) => rr !== runningRequest);
                     resolve();
@@ -527,7 +542,10 @@ class BuildRouter extends Router {
                 this._runningReqs
                     .filter((req) => {
                         if (req.started < threshold) {
-                            this._logger.error('BuildRouter EXPIRE filter', req);
+                            this._logger.error('BuildRouter EXPIRE filter', {
+                                ...BuildRouter._expireInfo(req.args, this.runningReqTimeout),
+                                startedAt: new Date(req.started).toISOString()
+                            });
                             return false;
                         }
                         return true;

package/src/CallbackAuditLog.js

@@ -35,11 +35,7 @@ const TYPE_INFO = 'Info';
  * @prop {string} [ro] - referrer || origin
  */
 
-/**
- * @typedef {object} Logger
- * @prop {Function} log
- * @prop {Function} error
- */
+/** @typedef {import('./log/types').LevelLogger} Logger */
 
 /**
  * @typedef {object} AuditLogEntry

package/src/ChatGpt.js

@@ -4,7 +4,6 @@
 'use strict';
 
 const nodeFetch = require('node-fetch').default;
-const util = require('util');
 const { PHONE_REGEX, EMAIL_REGEX } = require('./systemEntities/regexps');
 const LLM = require('./LLM');
 
@@ -101,11 +100,7 @@ const LLM = require('./LLM');
  * @prop {ChatGPTUsage} usage
  */
 
-/**
- * @typedef {object} Logger
- * @prop {Function} log
- * @prop {Function} error
- */
+/** @typedef {import('./log/types').LevelLogger} Logger */
 
 /**
  * @typedef {object} GptToolCall
@@ -178,6 +173,9 @@ const LLM = require('./LLM');
 /**
  * @class ChatGpt
  */
+// how much of the input and the output the info row of an LLM call keeps
+const SUMMARY_TEXT_LENGTH = 2000;
+
 class ChatGpt {
 
     /**
@@ -242,15 +240,41 @@ class ChatGpt {
         return this._options.model;
     }
 
-    _log (msg, ...args) {
-        if (this._logger === console) {
-
-            this._logger.log(msg, ...args.map((arg) => util.inspect(arg, {
-                showHidden: false, depth: null, colors: true
-            })));
-        } else {
-            this._logger.log(msg, ...args);
-        }
+    /**
+     * The info row of one LLM call: the new input (the last message, not the
+     * whole transcript), the output and the usage. The whole request and
+     * response are in the debug rows.
+     *
+     * @param {object} body - the request body
+     * @param {ChatGPTChoice} choice
+     * @param {LLMUsage} usage
+     * @param {number} durationMs
+     * @returns {object}
+     */
+    static _summary (body, choice, usage, durationMs) {
+        const { messages = [], tools = [] } = body;
+        const last = messages[messages.length - 1] || {};
+        const { message = {}, finish_reason: finishReason } = choice || {};
+        const cut = (text) => (typeof text === 'string' && text.length > SUMMARY_TEXT_LENGTH
+            ? `${text.slice(0, SUMMARY_TEXT_LENGTH)}… (${text.length - SUMMARY_TEXT_LENGTH} more chars)`
+            : text);
+        return {
+            ...usage,
+            durationMs,
+            finishReason,
+            messageCount: messages.length,
+            toolCount: tools.length,
+            input: { role: last.role, content: cut(last.content) },
+            output: cut(message.content),
+            ...(message.tool_calls && message.tool_calls.length
+                ? {
+                    toolCalls: message.tool_calls.map((tc) => ({
+                        name: tc.function && tc.function.name,
+                        args: cut(tc.function && tc.function.arguments)
+                    }))
+                }
+                : {})
+        };
     }
 
     /**
@@ -457,7 +481,8 @@ class ChatGpt {
 
             const apiUrl = `${this._openAiEndpoint}/chat/completions${this._apiKey ? `?api-version=${encodeURIComponent(this._apiVersion)}` : ''}`;
 
-            this._log('#GPT request', body);
+            // the whole prompt: verbose only (or replayed with an error)
+            this._logger.debug('#GPT request', body);
 
             const startTime = Date.now();
             const response = await this._fetch(apiUrl, {
@@ -508,11 +533,14 @@ class ChatGpt {
 
             const durationMs = Date.now() - startTime;
 
-            this._log('#GPT response', { choice, responseData, durationMs });
+            this._logger.debug('#GPT response body', { responseData, durationMs });
+            this._logger.info('#GPT response', ChatGpt._summary(body, choice, llmUsage, durationMs));
 
             return { choice, usage: llmUsage };
         } catch (e) {
-            this._logger.log('#GPT failed', {
+            // the caller logs the error once (LLMSession: the fallback message);
+            // the detail goes with it (replayed with the error)
+            this._logger.debug('#GPT failed', {
                 message: e.message, body, responseText, responseData, status, statusText
             });
             throw e;

package/src/ConversationTester.js

@@ -95,11 +95,7 @@ const DEFAULT_TEXT_THRESHOLD = 0.8;
  * @prop {number} stepCount
  */
 
-/**
- * @typedef {object} Logger
- * @prop {Function} log
- * @prop {Function} error
- */
+/** @typedef {import('./log/types').LevelLogger} Logger */
 
 /**
  * Automated Conversation tests runner

package/src/LLM.js

@@ -60,6 +60,7 @@ const LLMSession = require('./LLMSession');
  * @typedef {object} PrepocessedRuleData
  * @prop {Function} condition
  * @prop {PreprocessorOutput} rule
+ * @prop {string[]} [aiTags] - original rule definition (from the designer), for logs
  */
 
 /**
@@ -75,12 +76,24 @@ const LLMSession = require('./LLMSession');
  * @typedef {RuleScore & PreprocessedRule} RuleWithScore
  */
 
+/**
+ * @typedef {object} EvaluatedRule
+ * @prop {string|number} [id]
+ * @prop {EvaluationRuleAction} [action]
+ * @prop {string[]} [aiTags]
+ * @prop {boolean} conditionPassed - false, when the rule was skipped by its condition
+ * @prop {number} score - 0, when the rule did not match at all
+ * @prop {boolean} matched - score reached the threshold
+ */
+
 /**
  * @typedef {object} EvaluationResult
  * @prop {string} action
  * @prop {boolean} discard
  * @prop {RuleWithScore[]} results
  * @prop {object} setState
+ * @prop {number} [threshold] - minimal score of a matching rule
+ * @prop {EvaluatedRule[]} [evaluated] - every rule and the decision made about it
  */
 
 /**
@@ -190,11 +203,7 @@ const LLMSession = require('./LLMSession');
  * @prop {LogPrompt} logPrompt
  */
 
-/**
- * @typedef {object} Logger
- * @prop {Function} log
- * @prop {Function} error
- */
+/** @typedef {import('./log/types').LevelLogger} Logger */
 
 /**
  * @typedef {object} VectorSearchDocument
@@ -527,6 +536,8 @@ class LLM {
 
             return {
                 ...rest,
+                // kept, so logs can show the rule as it was defined in the designer
+                aiTags,
                 condition,
                 rule
             };
@@ -559,14 +570,27 @@ class LLM {
         const setState = {};
 
         const sAct = Object.values(LLM.EVALUATION_ACTIONS);
+        const { threshold } = this._ai;
+
+        /** @type {EvaluatedRule[]} */
+        const evaluated = [];
 
         const results = rules
-            .filter((rule) => rule.condition(req, res))
+            .filter((rule) => {
+                const conditionPassed = !!rule.condition(req, res);
+                if (!conditionPassed) {
+                    evaluated.push(LLM._describeRule(rule, false, 0, threshold));
+                }
+                return conditionPassed;
+            })
             .map((rule) => {
                 const matched = this._ai.matcher
                     .matchText(text, rule.rule, nlpResult, state);
 
-                if (!matched || matched.score < this._ai.threshold) {
+                const score = matched ? matched.score : 0;
+                evaluated.push(LLM._describeRule(rule, true, score, threshold));
+
+                if (!matched || matched.score < threshold) {
                     return null;
                 }
 
@@ -594,10 +618,51 @@ class LLM {
             setState,
             results,
             discard,
-            action: discard ? null : topRankedAction
+            action: discard ? null : topRankedAction,
+            threshold,
+            evaluated
+        };
+    }
+
+    /**
+     * Rule as a plain object for logs (RegExp objects serialize as {})
+     *
+     * @param {PreprocessedRule} rule
+     * @param {boolean} conditionPassed
+     * @param {number} score
+     * @param {number} threshold
+     * @returns {EvaluatedRule}
+     */
+    static _describeRule (rule, conditionPassed, score, threshold) {
+        // @ts-ignore
+        const { id, action = null, aiTags } = rule;
+        return {
+            id,
+            action,
+            aiTags: aiTags || LLM._ruleTags(rule.rule),
+            conditionPassed,
+            score,
+            matched: conditionPassed && score >= threshold
         };
     }
 
+    /**
+     * Fallback for rules added without their definition
+     *
+     * @param {PreprocessorOutput} rule
+     * @returns {string[]}
+     */
+    static _ruleTags (rule) {
+        if (!rule) return [];
+        /** @type {any} */
+        const r = rule;
+        return [
+            ...(r.regexps || []).map((x) => `regexp:${x.r instanceof RegExp ? x.r.source : x.r}`),
+            ...(r.intents || []).map((i) => `intent:${i}`),
+            ...(r.entities || []).map((e) => `@${e.entity}${e.optional ? '?' : ''}`)
+        ];
+    }
+
 }
 
 module.exports = LLM;

package/src/LLMDispatcher.js

@@ -39,11 +39,7 @@ const BASE64_REGEX = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{
  * @prop {RouterResolver} resolve
  */
 
-/**
- * @typedef {object} Logger
- * @prop {Function} log
- * @prop {Function} error
- */
+/** @typedef {import('./log/types').LevelLogger} Logger */
 
 /**
  * @typedef {object} DispatcherOptions

package/src/LLMSession.js

@@ -429,7 +429,7 @@ class LLMSession {
         } else if (errors.length) {
             // @ts-ignore
             const errs = errors.map((e) => e.error);
-            this._llm.log.log('LLMSession failures', errs);
+            this._llm.log.debug('LLMSession failures', { errors: errs.map((e) => e.message) });
             throw new Error(errs.map((e) => e.message).join(', '));
         }
     }

package/src/Processor.js

@@ -14,6 +14,7 @@ const { prepareState, mergeState, isUserInteraction } = require('./utils/stateVa
 const LLM = require('./LLM');
 const LLMMockProvider = require('./LLMMockProvider');
 const LLMDispatcher = require('./LLMDispatcher');
+const logSpan = require('./utils/logSpan');
 
 /** @typedef {import('./wingbot/CustomEntityDetectionModel').Intent} Intent */
 /** @typedef {import('./ReducerWrapper')} ReducerWrapper */
@@ -85,12 +86,7 @@ const LLMDispatcher = require('./LLMDispatcher');
  * @type {InteractionEvent}
  */
 
-/**
- * @typedef {object} ILogger
- * @prop {Function} log
- * @prop {Function} warn
- * @prop {Function} error
- */
+/** @typedef {import('./log/types').LevelLogger} ILogger */
 
 /**
  *
@@ -314,7 +310,7 @@ class Processor extends EventEmitter {
 
     async _reportError (pageId, err, event, senderId = null) {
         if (err.code === 204) {
-            this.options.log.log(`nothing sent: ${err.message}`, event);
+            this.options.log.debug('nothing sent', { message: err.message, senderId, pageId });
             return;
         }
         if (err.code !== 403) {
@@ -335,7 +331,9 @@ class Processor extends EventEmitter {
 
             await this.stateStorage.saveState(state);
         } catch (e) {
-            this.options.log.error(`failed to log error "${err.message}" because: ${e.message}`, e, err);
+            this.options.log.error('Failed to store the send error to the state', e, {
+                senderId, pageId, sendError: err.message
+            });
         }
     }
 
@@ -364,6 +362,20 @@ class Processor extends EventEmitter {
         ),
         responderData = {}
     ) {
+        const senderId = message && ((message.sender && message.sender.id)
+            || (message.optin && message.optin.user_ref));
+
+        // one span per processed event: its logs, LLM and storage calls share
+        // the operation, and the span carries the conversation (senderId)
+        return logSpan(
+            this.options.log,
+            'wingbot processMessage',
+            () => this._handleMessage(message, pageId, messageSender, responderData),
+            { senderId, pageId }
+        );
+    }
+
+    async _handleMessage (message, pageId, messageSender, responderData) {
         const preloadPromise = this._preload();
 
         try {
@@ -1052,7 +1064,9 @@ class Processor extends EventEmitter {
                         this.stateStorage
                             .getState(senderId, pageId)
                             .then((state) => {
-                                this.options.log.warn(`Locked state: ${senderId}, lock: ${lock}, at ${Date.now()}`, state);
+                                this.options.log.warn('Locked state', {
+                                    senderId, pageId, lock, state
+                                });
                             })
                             .catch(() => {});
 
@@ -1085,7 +1099,9 @@ class Processor extends EventEmitter {
             const duration = Date.now() - now;
             if (duration >= (this.options.waitForLockedState / 2)) {
                 try {
-                    this.options.log.warn(`Loading state (${senderId}) for timeout ${timeout} took too long (${duration}ms).`);
+                    this.options.log.warn('Loading state took too long', {
+                        senderId, pageId, timeout, durationMs: duration
+                    });
                 } catch (e) {
                     // noop
                 }

package/src/Request.js

@@ -173,6 +173,11 @@ class Request {
          */
         this.params = {};
 
+        /**
+         * @type {S} current state of the conversation
+         */
+        this.state = state;
+
         this.message = event.message || null;
 
         let usePostBack;
@@ -222,11 +227,6 @@ class Request {
          */
         this.pageId = pageId;
 
-        /**
-         * @type {S} current state of the conversation
-         */
-        this.state = state;
-
         /**
          * @type {string[]} features supported messaging features
          */
@@ -1353,10 +1353,12 @@ It looks like the bot isn't connected to class BotApp or the Processor is used w
         features = [FEATURE_TEXT]
     ) {
         const postback = {
-            payload: {
-                action,
-                data
-            }
+            payload: data === null
+                ? action
+                : {
+                    action,
+                    data
+                }
         };
         if (refAction) {
             Object.assign(postback, {

package/src/analytics/GA4.js

@@ -126,7 +126,7 @@ class GA4 {
         };
 
         if (this._options.debug) {
-            this._logger.log('GA4: starting session', event);
+            this._logger.debug('GA4: starting session', event);
         }
 
         const query = Object.entries(event)
@@ -255,15 +255,15 @@ class GA4 {
 
             message = (validationMessages[0] || { description: message }).description;
         } catch (e) {
-            this._logger.log('GA4 debug failed', e);
+            this._logger.warn('GA4 debug failed', e);
             message += ` +(${e.message})`;
         }
 
         if (validationMessages.length || message) {
-            this._logger.log('GA4: validationMessages', validationMessages);
+            this._logger.debug('GA4: validationMessages', { validationMessages });
             this._logger.error(`GA4: fail: ${message} [${res ? res.status : 0}]`, params.body);
         } else {
-            this._logger.log(`GA4: debug [${res ? res.status : 0}]`, params.body);
+            this._logger.debug('GA4: debug', { status: res ? res.status : 0, body: params.body });
         }
     }
 

package/src/graphApi/GraphApi.js

@@ -28,11 +28,7 @@ const DEFAULT_CACHE = 86400000; // 24 hours
 /** @typedef {import('../CallbackAuditLog')} AuditLog */
 /** @typedef {import('graphql')} GqlLib */
 
-/**
- * @typedef {object} Logger
- * @prop {Function} log
- * @prop {Function} error
- */
+/** @typedef {import('../log/types').LevelLogger} Logger */
 
 class GraphApi {
 

package/src/graphApi/gqlRules.js

@@ -10,11 +10,7 @@ const {
 
 /** @typedef {import('graphql').ValidationRule} ValidationRule */
 
-/**
- * @typedef {object} Logger
- * @prop {Function} log
- * @prop {Function} error
- */
+/** @typedef {import('../log/types').LevelLogger} Logger */
 
 /**
  *
@@ -58,7 +54,7 @@ function gqlRules (variables, isProduction, hideVerboseErrors, log = console) {
             // This can be used for logging or to implement rate limiting
             onComplete: (complexity) => {
                 if (!isProduction) {
-                    log.log('Determined query complexity: ', complexity);
+                    log.debug('Determined query complexity', { complexity });
                 }
             },
 
@@ -70,7 +66,7 @@ function gqlRules (variables, isProduction, hideVerboseErrors, log = console) {
                     log.error(msg);
                     return new GraphQLError('');
                 }
-                log.log(msg);
+                log.warn('GQL Query too complex', { actual, max });
                 return new GraphQLError(`Query is too complex: ${actual}. Maximum allowed complexity: ${max}`);
             },
 

package/src/log/types.js

@@ -0,0 +1,98 @@
+// GENERATED COPY of wingbot-super/packages/log/src/types.js - do not edit here.
+// Edit packages/log, then run: node packages/log/scripts/copy.mjs packages/wingbot-llm
+/**
+ * @author wingbot.ai
+ *
+ * The types of a log call, shared by the logger and the libraries that get
+ * it (wingbot, the orchestrator). Types only, no code: `scripts/copy.mjs`
+ * copies this file into the apps (next to the logger) and into the
+ * libraries (targets.json, `files: ["types"]`), so they import
+ * `LevelLogger` instead of declaring their own `Logger`.
+ */
+'use strict';
+
+/**
+ * A log call: `(message, [Error], [data...])`, the arguments in any order.
+ * The first Error is the exception, plain objects are merged into the data,
+ * other values go to `data.args`.
+ *
+ * Rules for every log call:
+ * 1. **The message is a constant**, the values go to the data:
+ *    `log.warn('SAP getList failed', { status, taskType })`, not
+ *    `` `SAP getList failed ${status}` ``. Never put `e.stack` or
+ *    `JSON.stringify(...)` into the message: pass the Error, pass the object.
+ *    (Only the first line, max 200 chars, becomes the message / App Insights
+ *    event name; the rest goes to `fullMessage`.)
+ * 2. **Log once, where the error is handled.** An adapter (SapApi,
+ *    MicrosoftApi) does not log a failure it throws: it calls
+ *    `log.annotate({...})` and throws an Error with the context
+ *    (`new Error(msg, { cause })`). The code that decides what happens (retry
+ *    later, show an error, return 500) logs it once. Logging the same Error
+ *    object again is marked as a duplicate and not reported again.
+ * 3. **Never log** a raw request / event, headers, cookies, tokens or config:
+ *    use `requestLogInfo(event)`. Secret-looking keys, the `queryKeys` and the
+ *    configured secret values are redacted anyway, but do not rely on it.
+ *    Personal data (emails, transcripts) is allowed. How much data:
+ *    - `debug`: the detail, whole objects too (the task, the slot, the
+ *      transcript). It is written with `verbose`, or with the error of the
+ *      trace (`replayOnError`), and cut by `redact` (`maxString`, `maxDepth`,
+ *      `maxArray`).
+ *    - `info`: the ids and the small values that explain the event (statuses,
+ *      reason, emails), not whole objects: it is always written.
+ *    - `warn` / `error`: what is needed to fix it, whole objects too.
+ * 4. **Wrap non-HTTP work** (worker runs, sync runs, queues) in `log.span()`,
+ *    and call `await log.sendAndClose()` at the end of a lambda or worker run
+ *    (it flushes only on Lambda; `{ force: true }` before the process exits).
+ * 5. **One row per business event.** A storage read or write that must be
+ *    audited is `log.audit()`, other detail is `debug`. The decision about a
+ *    task or slot (created, rejected and why, status changed) is one `info`
+ *    row with the ids.
+ *
+ * @callback LogFn
+ * @param {any} message - a CONSTANT text: values go to the data, never `e.stack`
+ *  or `JSON.stringify(...)` in it (only its first line, max 200 chars, is kept as
+ *  the message). An Error is accepted too.
+ * @param {...any} args - the Error (pass it, do not stringify it) and data objects
+ *  (`slotId`, `taskId`, ...; whole objects in `debug`, `warn` and `error`).
+ *  Never a raw request, event, headers, tokens or config: use
+ *  `requestLogInfo(event)`.
+ * @returns {void}
+ */
+
+/** @typedef {<T>(name: string, fn: () => T|Promise<T>, attrs?: object) => Promise<T>} SpanFn */
+
+/**
+ * What a library needs from a logger: the five levels. `console`, the shared
+ * logger (lib/log of an app) and the orchestrator's moduleLoggerFactory
+ * logger have them. `span` is optional: the shared logger has it, a library
+ * checks it before the call (`console` has none).
+ *
+ * Use it in a library as the typedef
+ * `{import('./log/types').LevelLogger} Logger`.
+ *
+ * @typedef {object} LevelLogger
+ * @prop {LogFn} error **Someone must act**: a bug, lost or wrong data, an
+ *  upstream call that failed after the retries, a business result that was not
+ *  saved. Goes to App Insights (AppEvents, AppExceptions) and to Sentry, and
+ *  triggers the error alerts, so do NOT use it for client mistakes or for
+ *  handled states. Log it once, where the error is handled: an adapter that
+ *  throws calls `log.annotate()` instead.
+ *  Examples: a result written to the wrong row, `Bot preloader is not set`,
+ *  SAP setResult failed after the retries.
+ * @prop {LogFn} warn **Degraded, but handled**: a 4xx from a client (bad
+ *  body, invalid token), a transient upstream error before a retry, a discarded
+ *  LLM reply, a duplicate-key retry, a fallback that was used.
+ *  Examples: `HTTP 400 POST /api`, SAP timeout (next run retries), #CANARY.
+ * @prop {LogFn} info **Business events and expected states**: a slot opened,
+ *  a task synced, an email sent, a test whitelist block, a missing translation.
+ *  Dropped unless `verbose` (verboseLog in config). AppTraces.
+ * @prop {LogFn} log like `info`, but always written (AppEvents). Kept for the
+ *  old call sites; prefer `info` (an event worth seeing in production) or
+ *  `debug` (detail).
+ * @prop {LogFn} debug **Detail**: payloads, request / response bodies, step by
+ *  step flow. Dropped unless `verbose`.
+ * @prop {SpanFn} [span] Runs `fn` in a child span (the shared logger only):
+ *  see `LogFunctions.span` of the shared logger.
+ */
+
+module.exports = {};

package/src/notifications/Notifications.js

@@ -110,11 +110,7 @@ const DEFAULT_CAMPAIGN_DATA = {
  * @prop {object} meta
  */
 
-/**
- * @typedef {object} Logger
- * @prop {Function} log
- * @prop {Function} error
- */
+/** @typedef {import('../log/types').LevelLogger} Logger */
 
 /** @typedef {import('./api/notificationsApiFactory').NotificationsApiOptions} ApiOptions */
 

package/src/resolvers/message.js

@@ -457,6 +457,7 @@ function message (params, context = {}) {
             let session;
             let evaluation;
             let discard;
+            let llmError;
 
             try {
                 session = res.llmSessionWithHistory(params.llmContextType);
@@ -467,13 +468,25 @@ function message (params, context = {}) {
                 ({ discard } = evaluation);
             } catch (e) {
                 (context.log || console).error(`LLM ERR: ${e.message} [${req.senderId}]`, e);
+                llmError = e;
                 discard = true;
             }
 
             if (discard) {
+                // short summary: where it happened, what the LLM generated,
+                // what is sent instead and why (every rule with its score)
                 canaryLog(context.log, context.canaryLogs, 'LLM discarded', {
-                    evaluation,
-                    session
+                    reason: llmError ? 'llm-error' : 'rule-matched',
+                    ...(llmError && { error: llmError.message }),
+                    source: {
+                        resolverId,
+                        action: req.action(),
+                        contextType: params.llmContextType || null
+                    },
+                    generated: (llmError ? null : session?.lastResponseSync()) || null,
+                    fallbackText: text,
+                    threshold: evaluation?.threshold ?? null,
+                    rules: evaluation?.evaluated ?? []
                 });
             } else {
 

package/src/utils/canaryLog.js

@@ -3,12 +3,7 @@
  */
 'use strict';
 
-/**
- * @typedef {object} ILogger
- * @prop {Function} log
- * @prop {Function} warn
- * @prop {Function} error
- */
+/** @typedef {import('../log/types').LevelLogger} ILogger */
 
 /**
  *

package/src/utils/logSpan.js

@@ -0,0 +1,36 @@
+/**
+ * @author wingbot.ai
+ */
+'use strict';
+
+/**
+ * @typedef {object} SpanLogger
+ * @prop {<T>(name: string, fn: () => T|Promise<T>, attributes?: object) => Promise<T>} [span]
+ */
+
+/**
+ * Runs `fn` in a span of the app logger, when the logger has `span()`
+ * (the shared wingbot logger: an OpenTelemetry span, App Insights and Sentry).
+ * Other loggers (console) only run `fn`.
+ *
+ * The attributes without a value are left out.
+ *
+ * @template T
+ * @param {SpanLogger|any} log
+ * @param {string} name
+ * @param {() => T|Promise<T>} fn
+ * @param {Record<string, any>} [attributes]
+ * @returns {Promise<T>}
+ */
+async function logSpan (log, name, fn, attributes = {}) {
+    if (!log || typeof log.span !== 'function') {
+        return fn();
+    }
+    const attrs = Object.keys(attributes)
+        .filter((key) => attributes[key] !== undefined && attributes[key] !== null)
+        .reduce((o, key) => Object.assign(o, { [key]: attributes[key] }), {});
+
+    return log.span(name, fn, attrs);
+}
+
+module.exports = logSpan;

package/src/utils/pathUtils.js

@@ -45,8 +45,14 @@ function parseActionPayload (object, needRawData = false) {
         let isObject = typeof payload === 'object' && payload !== null;
 
         if (typeof payload === 'string' && payload.match(/^\s*\{.*\}\s*$/)) {
-            payload = JSON.parse(payload);
-            isObject = true;
+            try {
+                payload = JSON.parse(payload);
+                isObject = true;
+            } catch (e) {
+                if (!(e instanceof SyntaxError)) throw e;
+                // broken JSON from the client: an unknown action, not a 500
+                // (the action check below rejects the raw string)
+            }
         }
 
         if (isObject) {

package/src/wingbot/CachedModel.js

@@ -98,7 +98,11 @@ class CachedModel extends CustomEntityDetectionModel {
             .filter((e) => this._entityDetectors.has(e.entity)
                 && this._entityDetectors.get(e.entity).clearOverlaps);
 
-        if (this._options.verbose) this._log.log(`#NLP: ${text} [before]`, { before, intents, entities });
+        if (this._options.verbose) {
+            this._log.debug('#NLP before', {
+                text, before, intents, entities
+            });
+        }
 
         [intents, entities] = this._attachEntities(intents, entities, before, expectedEntities);
 
@@ -106,11 +110,19 @@ class CachedModel extends CustomEntityDetectionModel {
             .filter((e) => !this._entityDetectors.has(e.entity)
                 || !this._entityDetectors.get(e.entity).clearOverlaps);
 
-        if (this._options.verbose) this._log.log(`#NLP: ${text} [after]`, { after, intents, entities });
+        if (this._options.verbose) {
+            this._log.debug('#NLP after', {
+                text, after, intents, entities
+            });
+        }
 
         [intents, entities] = this._attachEntities(intents, entities, after);
 
-        if (this._options.verbose) this._log.log(`#NLP: ${text} [attached]`, { intents, entities, expectedEntities });
+        if (this._options.verbose) {
+            this._log.debug('#NLP attached', {
+                text, intents, entities, expectedEntities
+            });
+        }
 
         return {
             text: local.text,

package/src/wingbot/CustomEntityDetectionModel.js

@@ -304,7 +304,7 @@ class CustomEntityDetectionModel {
             return zLen - aLen;
         });
 
-        if (this._options.verbose) this._log.log('#NLP [nonOverlapping]', { entities, expectedEntities, justDuplicates });
+        if (this._options.verbose) this._log.debug('#NLP [nonOverlapping]', { entities, expectedEntities, justDuplicates });
 
         let res = [];
 
@@ -354,7 +354,7 @@ class CustomEntityDetectionModel {
                         const othersConflict = res.some((e) => putback === e
                             || (e.start < putback.end && e.end > putback.start));
 
-                        this._log.log(`#NLP (${i}|${k} [putBack: ${entity.entity}|${putback.entity}] (${i}|${k})`, {
+                        this._log.debug(`#NLP (${i}|${k} [putBack: ${entity.entity}|${putback.entity}] (${i}|${k})`, {
                             putback, entity, currentConflict, othersConflict
                         });
 
@@ -366,7 +366,7 @@ class CustomEntityDetectionModel {
             }
 
             if (this._options.verbose) {
-                this._log.log(`#NLP (${i}) [nonOverlapping| ${entity.entity}:${entity.value}]`, {
+                this._log.debug(`#NLP (${i}) [nonOverlapping| ${entity.entity}:${entity.value}]`, {
                     willRemoveEntity: overlapping, overlapping, duplicate, isExpected, entity
                 });
             }

package/src/wingbot/WingbotModel.js

@@ -109,7 +109,7 @@ class WingbotModel extends CachedModel {
             `matches=${encodeURIComponent(this._matches)}`
         ];
 
-        if (this._options.verbose) this._log.log(`#NLP: ${text} [query]`, { matches: this._matches, localEntities: entities });
+        if (this._options.verbose) this._log.debug('#NLP query', { text, matches: this._matches, localEntities: entities });
 
         if (entities) {
             const buf = await this._brotli(Buffer.from(JSON.stringify({ entities })));
@@ -124,7 +124,7 @@ class WingbotModel extends CachedModel {
 
             if (res.status === 403) {
                 // model does not exist
-                this._log.log(`NLP model '${this._model}' does not exist or is not deployed yet.`);
+                this._log.warn('NLP model does not exist or is not deployed yet', { model: this._model });
                 return { intents: [], entities: [] };
             }
 
@@ -136,7 +136,7 @@ class WingbotModel extends CachedModel {
                 throw new Error(`[${res.status}] Invalid JSON response: ${responseText}`);
             }
 
-            if (this._options.verbose) this._log.log(`#NLP: ${text} [response]`, response);
+            if (this._options.verbose) this._log.debug('#NLP response', { text, response });
 
             if (res.status >= 300) {
                 this._log.warn(`AI query failed: ${response.message || res.statusText}`);