@sprucelabs/sprucebot-llm 18.1.0 → 18.1.1

package/build/esm/parsingResponses/ResponseParserV2.d.ts

@@ -1,4 +1,10 @@
 import { ResponseParser, LlmCallbackMap, ParsedResponse } from '../llm.types';
+/**
+ * Always produce a serializable error representation for @results.
+ * Plain Error becomes its message (never {}). Schema-like errors with enumerable
+ * payload fall back to message string for a stable wire format.
+ */
+export declare function serializeCallbackError(err: unknown): string;
 export default class ResponseParserV2 implements ResponseParser {
     parse(response: string, callbacks?: LlmCallbackMap): Promise<ParsedResponse>;
     private invokeCallbacks;

package/build/esm/parsingResponses/ResponseParserV2.js

@@ -9,14 +9,186 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 import { DONE_TOKEN } from '../bots/templates.js';
 import validateAndNormalizeCallbackOptions from './validateAndNormalizeCallbackOptions.js';
+const RESERVED_CALLBACK_NAMES = new Set(['updateState', 'results']);
+/**
+ * Always produce a serializable error representation for @results.
+ * Plain Error becomes its message (never {}). Schema-like errors with enumerable
+ * payload fall back to message string for a stable wire format.
+ */
+export function serializeCallbackError(err) {
+    if (err instanceof Error) {
+        return err.message && err.message.length > 0 ? err.message : 'Error';
+    }
+    if (typeof err === 'string') {
+        return err;
+    }
+    if (err === null) {
+        return 'null';
+    }
+    if (err === undefined) {
+        return 'undefined';
+    }
+    if (typeof err === 'symbol') {
+        return String(err);
+    }
+    try {
+        const json = JSON.stringify(err);
+        if (json && json !== '{}') {
+            return json;
+        }
+    }
+    catch (_a) {
+        // fall through
+    }
+    try {
+        return String(err);
+    }
+    catch (_b) {
+        return 'Unknown error';
+    }
+}
+/** Find matching closing brace for a JSON object starting at openIdx ('{'). */
+function findMatchingBrace(text, openIdx) {
+    let depth = 0;
+    let inString = false;
+    let escape = false;
+    for (let i = openIdx; i < text.length; i++) {
+        const ch = text[i];
+        if (inString) {
+            if (escape) {
+                escape = false;
+                continue;
+            }
+            if (ch === '\\') {
+                escape = true;
+                continue;
+            }
+            if (ch === '"') {
+                inString = false;
+            }
+            continue;
+        }
+        if (ch === '"') {
+            inString = true;
+            continue;
+        }
+        if (ch === '{') {
+            depth++;
+        }
+        else if (ch === '}') {
+            depth--;
+            if (depth === 0) {
+                return i;
+            }
+        }
+    }
+    return -1;
+}
+/**
+ * Extract @name(...) call spans. Supports multi-line JSON objects via brace-depth
+ * scanning and optional leading/trailing whitespace on the call line.
+ */
+function extractCallbackSpans(message) {
+    const spans = [];
+    const re = /^[ \t]*@([A-Za-z_]\w*)\(/gm;
+    let m;
+    while ((m = re.exec(message)) !== null) {
+        const name = m[1];
+        const start = m.index;
+        const openParen = m.index + m[0].length - 1;
+        let i = openParen + 1;
+        while (i < message.length && /[ \t\r\n]/.test(message[i])) {
+            i++;
+        }
+        let argsJson;
+        let closeParen;
+        if (i < message.length && message[i] === ')') {
+            closeParen = i;
+            argsJson = undefined;
+        }
+        else if (i < message.length && message[i] === '{') {
+            const braceEnd = findMatchingBrace(message, i);
+            if (braceEnd < 0) {
+                spans.push({
+                    name,
+                    fullMatch: message.slice(start),
+                    start,
+                    end: message.length,
+                });
+                break;
+            }
+            argsJson = message.slice(i, braceEnd + 1);
+            let j = braceEnd + 1;
+            while (j < message.length && /[ \t\r\n]/.test(message[j])) {
+                j++;
+            }
+            if (j >= message.length || message[j] !== ')') {
+                spans.push({
+                    name,
+                    fullMatch: message.slice(start, braceEnd + 1),
+                    argsJson,
+                    start,
+                    end: braceEnd + 1,
+                });
+                re.lastIndex = braceEnd + 1;
+                continue;
+            }
+            closeParen = j;
+        }
+        else {
+            re.lastIndex = openParen + 1;
+            continue;
+        }
+        let end = closeParen + 1;
+        // Include trailing newline after the call when present (common LLM layout)
+        if (message[end] === '\r') {
+            end++;
+        }
+        if (message[end] === '\n') {
+            end++;
+        }
+        // Leading newline is part of fullMatch when start points after prior content;
+        // also absorb a single leading newline just before the match for strip parity
+        // with historic `\n@name(...)\n` fixtures.
+        let matchStart = start;
+        if (matchStart > 0 && message[matchStart - 1] === '\n') {
+            matchStart--;
+            if (matchStart > 0 && message[matchStart - 1] === '\r') {
+                matchStart--;
+            }
+        }
+        spans.push({
+            name,
+            fullMatch: message.slice(matchStart, end),
+            argsJson,
+            start: matchStart,
+            end,
+        });
+        re.lastIndex = end;
+    }
+    return spans;
+}
+function stripCallFromMessage(message, fullMatch) {
+    // Historic behavior: remove the call span and glue surrounding text without
+    // injecting separators (trim each side after split).
+    return message
+        .split(fullMatch)
+        .map((s) => s.trim())
+        .join('')
+        .trim();
+}
 export default class ResponseParserV2 {
     parse(response, callbacks) {
         return __awaiter(this, void 0, void 0, function* () {
             let message = response.replace(DONE_TOKEN, '').trim();
             let state = undefined;
             let callbackResults = undefined;
-            const hasCallbacks = callbacks != null &&
+            // Enter the pass when any @name( call shape is present (incl. typos)
+            // or when a registered callback name appears as a call prefix.
+            const hasCallShape = message != null && /^[ \t]*@\w+\(/m.test(message);
+            const hasRegisteredName = callbacks != null &&
                 Object.keys(callbacks).some((name) => message.includes(`@${name}(`));
+            const hasCallbacks = hasCallShape || hasRegisteredName;
             if (hasCallbacks) {
                 const { callbackResults: c, message: m } = yield this.invokeCallbacks(message, callbacks);
                 callbackResults = c;
@@ -53,26 +225,36 @@ export default class ResponseParserV2 {
     }
     invokeCallbacks(message, callbacks) {
         return __awaiter(this, void 0, void 0, function* () {
+            var _a;
             let callbackStrippedMessage = message;
             let callbackResults = '';
-            const reserved = new Set(['updateState', 'results']);
-            const matches = [...message.matchAll(/^@(\w+)\(({.*})?\)$/gm)];
-            for (const match of matches) {
-                if (reserved.has(match[1])) {
+            const spans = extractCallbackSpans(message);
+            for (const span of spans) {
+                if (RESERVED_CALLBACK_NAMES.has(span.name)) {
+                    continue;
+                }
+                const name = span.name;
+                // Always strip the call from the user-facing message once recognized.
+                callbackStrippedMessage = stripCallFromMessage(callbackStrippedMessage, span.fullMatch);
+                let options;
+                try {
+                    options = span.argsJson ? JSON.parse(span.argsJson) : undefined;
+                }
+                catch (err) {
+                    callbackResults += this.renderCallbackResults({
+                        name,
+                        error: `Invalid JSON arguments for @${name}: ${(_a = err === null || err === void 0 ? void 0 : err.message) !== null && _a !== void 0 ? _a : String(err)}. Arguments must be valid JSON object.`,
+                    });
                     continue;
                 }
-                const parsed = match[2] ? JSON.parse(match[2]) : undefined;
-                const name = match[1];
-                const options = parsed;
                 const callback = callbacks === null || callbacks === void 0 ? void 0 : callbacks[name];
                 if (!callback) {
+                    callbackResults += this.renderCallbackResults({
+                        name,
+                        error: `Unknown callback @${name} — not registered.`,
+                    });
                     continue;
                 }
-                const parts = callbackStrippedMessage.split(match[0]);
-                callbackStrippedMessage = parts
-                    .map((s) => s.trim())
-                    .join('')
-                    .trim();
                 try {
                     if (callback === null || callback === void 0 ? void 0 : callback.parameters) {
                         validateAndNormalizeCallbackOptions(callback.parameters, options);
@@ -89,7 +271,7 @@ export default class ResponseParserV2 {
             }
             callbackResults = callbackResults.trim();
             return {
-                callbackResults,
+                callbackResults: callbackResults.length > 0 ? callbackResults : undefined,
                 message: callbackStrippedMessage.length > 0
                     ? callbackStrippedMessage
                     : null,
@@ -97,35 +279,45 @@ export default class ResponseParserV2 {
         });
     }
     renderCallbackResults(callbackOptions) {
-        return `@results ${JSON.stringify(callbackOptions)}\n`;
+        const { name, results, error } = callbackOptions;
+        if (error !== undefined) {
+            return `@results ${JSON.stringify({
+                name,
+                error: serializeCallbackError(error),
+            })}\n`;
+        }
+        // Multiline string results: header only + raw body (real newlines).
+        // Trailing newline separates blocks when multiple callbacks run.
+        if (typeof results === 'string') {
+            return `@results ${JSON.stringify({ name })}\n${results}\n`;
+        }
+        // undefined results: omit results key (historic wire shape).
+        if (results === undefined) {
+            return `@results ${JSON.stringify({ name })}\n`;
+        }
+        return `@results ${JSON.stringify({ name, results })}\n`;
     }
     getStateUpdateInstructions() {
         return `Updating state works similar to all function calls. Use the following syntax:
 @updateState({ "field1": "value1", "field2": "value2" })
-Make sure to json encode only the fields you want to change. You can update state once and do it at the end of any messages you send. IMPORTANT: JSON must be on a single line. Do NOT use multi-line or formatted JSON.
+Make sure to json encode only the fields you want to change. You can update state once and do it at the end of any messages you send. Multi-line JSON objects are accepted (pretty-printed objects are parsed). IMPORTANT: Prefer a single JSON object argument; do not omit braces.
 Your user-facing message is always sent to the user, even if @updateState fails. If @updateState fails later, do not repeat the same message. Only send the specific @updateState needed to fix the missing state change.
 Good example:
 @updateState({ "favoriteColor": "blue", "firstName": "Taylor" })
 Bad examples:
 @updateState
 { "favoriteColor": "blue" }
-@updateState({
-  "favoriteColor": "blue"
-})
 @updateState({ favoriteColor: "blue" })`;
     }
     getFunctionCallInstructions() {
         return `A function call is done using the following syntax:
 @callbackName({ "key": "value" })
-Make sure to json encode the options. You can call as many callbacks as you want in a single response by including multiple @functionName() lines. IMPORTANT: JSON must be on a single line. Do NOT use multi-line or formatted JSON.
+Make sure to json encode the options. You can call as many callbacks as you want in a single response by including multiple @functionName() lines. Multi-line JSON arguments are accepted (pretty-printed objects are parsed). Failed callbacks always return a serializable error string in @results — never silence failures and never return an empty error object.
 Your user-facing message is always sent to the user, even if a callback fails. Successful callbacks have already run successfully. If a callback fails later, do not repeat the same message and do not repeat successful callbacks. Only call the specific callback needed to fix the failed gap.
 Good example:
 @lookupWeather({ "zip": "80524" })
 Bad examples:
 @lookupWeather { "zip": "80524" }
-@lookupWeather(
-{ "zip": "80524" }
-)
 @lookupWeather({ zip: "80524" })`;
     }
 }

package/build/parsingResponses/ResponseParserV2.d.ts

@@ -1,4 +1,10 @@
 import { ResponseParser, LlmCallbackMap, ParsedResponse } from '../llm.types';
+/**
+ * Always produce a serializable error representation for @results.
+ * Plain Error becomes its message (never {}). Schema-like errors with enumerable
+ * payload fall back to message string for a stable wire format.
+ */
+export declare function serializeCallbackError(err: unknown): string;
 export default class ResponseParserV2 implements ResponseParser {
     parse(response: string, callbacks?: LlmCallbackMap): Promise<ParsedResponse>;
     private invokeCallbacks;

package/build/parsingResponses/ResponseParserV2.js

@@ -3,15 +3,188 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.serializeCallbackError = serializeCallbackError;
 const templates_1 = require("../bots/templates");
 const validateAndNormalizeCallbackOptions_1 = __importDefault(require("./validateAndNormalizeCallbackOptions"));
+const RESERVED_CALLBACK_NAMES = new Set(['updateState', 'results']);
+/**
+ * Always produce a serializable error representation for @results.
+ * Plain Error becomes its message (never {}). Schema-like errors with enumerable
+ * payload fall back to message string for a stable wire format.
+ */
+function serializeCallbackError(err) {
+    if (err instanceof Error) {
+        return err.message && err.message.length > 0 ? err.message : 'Error';
+    }
+    if (typeof err === 'string') {
+        return err;
+    }
+    if (err === null) {
+        return 'null';
+    }
+    if (err === undefined) {
+        return 'undefined';
+    }
+    if (typeof err === 'symbol') {
+        return String(err);
+    }
+    try {
+        const json = JSON.stringify(err);
+        if (json && json !== '{}') {
+            return json;
+        }
+    }
+    catch {
+        // fall through
+    }
+    try {
+        return String(err);
+    }
+    catch {
+        return 'Unknown error';
+    }
+}
+/** Find matching closing brace for a JSON object starting at openIdx ('{'). */
+function findMatchingBrace(text, openIdx) {
+    let depth = 0;
+    let inString = false;
+    let escape = false;
+    for (let i = openIdx; i < text.length; i++) {
+        const ch = text[i];
+        if (inString) {
+            if (escape) {
+                escape = false;
+                continue;
+            }
+            if (ch === '\\') {
+                escape = true;
+                continue;
+            }
+            if (ch === '"') {
+                inString = false;
+            }
+            continue;
+        }
+        if (ch === '"') {
+            inString = true;
+            continue;
+        }
+        if (ch === '{') {
+            depth++;
+        }
+        else if (ch === '}') {
+            depth--;
+            if (depth === 0) {
+                return i;
+            }
+        }
+    }
+    return -1;
+}
+/**
+ * Extract @name(...) call spans. Supports multi-line JSON objects via brace-depth
+ * scanning and optional leading/trailing whitespace on the call line.
+ */
+function extractCallbackSpans(message) {
+    const spans = [];
+    const re = /^[ \t]*@([A-Za-z_]\w*)\(/gm;
+    let m;
+    while ((m = re.exec(message)) !== null) {
+        const name = m[1];
+        const start = m.index;
+        const openParen = m.index + m[0].length - 1;
+        let i = openParen + 1;
+        while (i < message.length && /[ \t\r\n]/.test(message[i])) {
+            i++;
+        }
+        let argsJson;
+        let closeParen;
+        if (i < message.length && message[i] === ')') {
+            closeParen = i;
+            argsJson = undefined;
+        }
+        else if (i < message.length && message[i] === '{') {
+            const braceEnd = findMatchingBrace(message, i);
+            if (braceEnd < 0) {
+                spans.push({
+                    name,
+                    fullMatch: message.slice(start),
+                    start,
+                    end: message.length,
+                });
+                break;
+            }
+            argsJson = message.slice(i, braceEnd + 1);
+            let j = braceEnd + 1;
+            while (j < message.length && /[ \t\r\n]/.test(message[j])) {
+                j++;
+            }
+            if (j >= message.length || message[j] !== ')') {
+                spans.push({
+                    name,
+                    fullMatch: message.slice(start, braceEnd + 1),
+                    argsJson,
+                    start,
+                    end: braceEnd + 1,
+                });
+                re.lastIndex = braceEnd + 1;
+                continue;
+            }
+            closeParen = j;
+        }
+        else {
+            re.lastIndex = openParen + 1;
+            continue;
+        }
+        let end = closeParen + 1;
+        // Include trailing newline after the call when present (common LLM layout)
+        if (message[end] === '\r') {
+            end++;
+        }
+        if (message[end] === '\n') {
+            end++;
+        }
+        // Leading newline is part of fullMatch when start points after prior content;
+        // also absorb a single leading newline just before the match for strip parity
+        // with historic `\n@name(...)\n` fixtures.
+        let matchStart = start;
+        if (matchStart > 0 && message[matchStart - 1] === '\n') {
+            matchStart--;
+            if (matchStart > 0 && message[matchStart - 1] === '\r') {
+                matchStart--;
+            }
+        }
+        spans.push({
+            name,
+            fullMatch: message.slice(matchStart, end),
+            argsJson,
+            start: matchStart,
+            end,
+        });
+        re.lastIndex = end;
+    }
+    return spans;
+}
+function stripCallFromMessage(message, fullMatch) {
+    // Historic behavior: remove the call span and glue surrounding text without
+    // injecting separators (trim each side after split).
+    return message
+        .split(fullMatch)
+        .map((s) => s.trim())
+        .join('')
+        .trim();
+}
 class ResponseParserV2 {
     async parse(response, callbacks) {
         let message = response.replace(templates_1.DONE_TOKEN, '').trim();
         let state = undefined;
         let callbackResults = undefined;
-        const hasCallbacks = callbacks != null &&
+        // Enter the pass when any @name( call shape is present (incl. typos)
+        // or when a registered callback name appears as a call prefix.
+        const hasCallShape = message != null && /^[ \t]*@\w+\(/m.test(message);
+        const hasRegisteredName = callbacks != null &&
             Object.keys(callbacks).some((name) => message.includes(`@${name}(`));
+        const hasCallbacks = hasCallShape || hasRegisteredName;
         if (hasCallbacks) {
             const { callbackResults: c, message: m } = await this.invokeCallbacks(message, callbacks);
             callbackResults = c;
@@ -48,24 +221,33 @@ class ResponseParserV2 {
     async invokeCallbacks(message, callbacks) {
         let callbackStrippedMessage = message;
         let callbackResults = '';
-        const reserved = new Set(['updateState', 'results']);
-        const matches = [...message.matchAll(/^@(\w+)\(({.*})?\)$/gm)];
-        for (const match of matches) {
-            if (reserved.has(match[1])) {
+        const spans = extractCallbackSpans(message);
+        for (const span of spans) {
+            if (RESERVED_CALLBACK_NAMES.has(span.name)) {
+                continue;
+            }
+            const name = span.name;
+            // Always strip the call from the user-facing message once recognized.
+            callbackStrippedMessage = stripCallFromMessage(callbackStrippedMessage, span.fullMatch);
+            let options;
+            try {
+                options = span.argsJson ? JSON.parse(span.argsJson) : undefined;
+            }
+            catch (err) {
+                callbackResults += this.renderCallbackResults({
+                    name,
+                    error: `Invalid JSON arguments for @${name}: ${err?.message ?? String(err)}. Arguments must be valid JSON object.`,
+                });
                 continue;
             }
-            const parsed = match[2] ? JSON.parse(match[2]) : undefined;
-            const name = match[1];
-            const options = parsed;
             const callback = callbacks?.[name];
             if (!callback) {
+                callbackResults += this.renderCallbackResults({
+                    name,
+                    error: `Unknown callback @${name} — not registered.`,
+                });
                 continue;
             }
-            const parts = callbackStrippedMessage.split(match[0]);
-            callbackStrippedMessage = parts
-                .map((s) => s.trim())
-                .join('')
-                .trim();
             try {
                 if (callback?.parameters) {
                     (0, validateAndNormalizeCallbackOptions_1.default)(callback.parameters, options);
@@ -82,42 +264,52 @@ class ResponseParserV2 {
         }
         callbackResults = callbackResults.trim();
         return {
-            callbackResults,
+            callbackResults: callbackResults.length > 0 ? callbackResults : undefined,
             message: callbackStrippedMessage.length > 0
                 ? callbackStrippedMessage
                 : null,
         };
     }
     renderCallbackResults(callbackOptions) {
-        return `@results ${JSON.stringify(callbackOptions)}\n`;
+        const { name, results, error } = callbackOptions;
+        if (error !== undefined) {
+            return `@results ${JSON.stringify({
+                name,
+                error: serializeCallbackError(error),
+            })}\n`;
+        }
+        // Multiline string results: header only + raw body (real newlines).
+        // Trailing newline separates blocks when multiple callbacks run.
+        if (typeof results === 'string') {
+            return `@results ${JSON.stringify({ name })}\n${results}\n`;
+        }
+        // undefined results: omit results key (historic wire shape).
+        if (results === undefined) {
+            return `@results ${JSON.stringify({ name })}\n`;
+        }
+        return `@results ${JSON.stringify({ name, results })}\n`;
     }
     getStateUpdateInstructions() {
         return `Updating state works similar to all function calls. Use the following syntax:
 @updateState({ "field1": "value1", "field2": "value2" })
-Make sure to json encode only the fields you want to change. You can update state once and do it at the end of any messages you send. IMPORTANT: JSON must be on a single line. Do NOT use multi-line or formatted JSON.
+Make sure to json encode only the fields you want to change. You can update state once and do it at the end of any messages you send. Multi-line JSON objects are accepted (pretty-printed objects are parsed). IMPORTANT: Prefer a single JSON object argument; do not omit braces.
 Your user-facing message is always sent to the user, even if @updateState fails. If @updateState fails later, do not repeat the same message. Only send the specific @updateState needed to fix the missing state change.
 Good example:
 @updateState({ "favoriteColor": "blue", "firstName": "Taylor" })
 Bad examples:
 @updateState
 { "favoriteColor": "blue" }
-@updateState({
-  "favoriteColor": "blue"
-})
 @updateState({ favoriteColor: "blue" })`;
     }
     getFunctionCallInstructions() {
         return `A function call is done using the following syntax:
 @callbackName({ "key": "value" })
-Make sure to json encode the options. You can call as many callbacks as you want in a single response by including multiple @functionName() lines. IMPORTANT: JSON must be on a single line. Do NOT use multi-line or formatted JSON.
+Make sure to json encode the options. You can call as many callbacks as you want in a single response by including multiple @functionName() lines. Multi-line JSON arguments are accepted (pretty-printed objects are parsed). Failed callbacks always return a serializable error string in @results — never silence failures and never return an empty error object.
 Your user-facing message is always sent to the user, even if a callback fails. Successful callbacks have already run successfully. If a callback fails later, do not repeat the same message and do not repeat successful callbacks. Only call the specific callback needed to fix the failed gap.
 Good example:
 @lookupWeather({ "zip": "80524" })
 Bad examples:
 @lookupWeather { "zip": "80524" }
-@lookupWeather(
-{ "zip": "80524" }
-)
 @lookupWeather({ zip: "80524" })`;
     }
 }

package/package.json

@@ -8,7 +8,7 @@
       "eta"
     ]
   },
-  "version": "18.1.0",
+  "version": "18.1.1",
   "files": [
     "build"
   ],
@@ -26,7 +26,8 @@
         "types": "./build/index.d.ts",
         "default": "./build/index.js"
       }
-    }
+    },
+    "./package.json": "./package.json"
   },
   "keywords": [
     "llm",