@promptbook/node 0.111.0-0 → 0.111.0-10

package/umd/index.umd.js

@@ -48,7 +48,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.111.0-0';
+    const PROMPTBOOK_ENGINE_VERSION = '0.111.0-10';
     /**
      * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
      * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -296,6 +296,188 @@
         }
     }
 
+    const SHORT_HEX_LENGTHS = new Set([3, 4]);
+    const LONG_HEX_LENGTHS = new Set([6, 8]);
+    /**
+     * Parses a hex string into RGBA channel values.
+     *
+     * @param hex - Hex value such as `#09d`, `009edd`, `#009eddff`.
+     * @returns RGBA channel values.
+     *
+     * @private function of Color
+     */
+    function parseHexColor(hex) {
+        const sanitized = hex.startsWith('#') ? hex.substring(1) : hex;
+        const throwInvalidHex = () => {
+            throw new Error(`Can not parse color from hex string "${hex}"`);
+        };
+        if (SHORT_HEX_LENGTHS.has(sanitized.length)) {
+            return {
+                red: parseShortHexChannel(sanitized.charAt(0), throwInvalidHex),
+                green: parseShortHexChannel(sanitized.charAt(1), throwInvalidHex),
+                blue: parseShortHexChannel(sanitized.charAt(2), throwInvalidHex),
+                alpha: sanitized.length === 4 ? parseShortHexChannel(sanitized.charAt(3), throwInvalidHex) : 255,
+            };
+        }
+        if (LONG_HEX_LENGTHS.has(sanitized.length)) {
+            return {
+                red: parseLongHexChannel(sanitized, 0, throwInvalidHex),
+                green: parseLongHexChannel(sanitized, 2, throwInvalidHex),
+                blue: parseLongHexChannel(sanitized, 4, throwInvalidHex),
+                alpha: sanitized.length === 8 ? parseLongHexChannel(sanitized, 6, throwInvalidHex) : 255,
+            };
+        }
+        return throwInvalidHex();
+    }
+    function parseShortHexChannel(char, onError) {
+        if (!char) {
+            return onError();
+        }
+        const parsed = parseInt(char, 16);
+        if (Number.isNaN(parsed)) {
+            return onError();
+        }
+        return parsed * 16;
+    }
+    function parseLongHexChannel(hex, start, onError) {
+        const segment = hex.substr(start, 2);
+        if (segment.length < 2) {
+            return onError();
+        }
+        const parsed = parseInt(segment, 16);
+        if (Number.isNaN(parsed)) {
+            return onError();
+        }
+        return parsed;
+    }
+
+    const HSL_REGEX = /^hsl\(\s*([0-9.]+)\s*,\s*([0-9.]+)%\s*,\s*([0-9.]+)%\s*\)$/;
+    /**
+     * Parses an HSL string into RGBA channel values.
+     *
+     * @param hsl - HSL string such as `hsl(197.1, 100%, 43.3%)`.
+     * @returns RGBA channel values.
+     *
+     * @private function of Color
+     */
+    function parseHslColor(hsl) {
+        const match = hsl.match(HSL_REGEX);
+        if (!match) {
+            throw new Error(`Invalid hsl string format: "${hsl}"`);
+        }
+        const hue = parseFloat(match[1]);
+        const saturation = parseFloat(match[2]) / 100;
+        const lightness = parseFloat(match[3]) / 100;
+        const { red, green, blue } = convertHslToRgb(hue, saturation, lightness);
+        return {
+            red,
+            green,
+            blue,
+            alpha: 255,
+        };
+    }
+    function convertHslToRgb(h, s, l) {
+        const c = (1 - Math.abs(2 * l - 1)) * s;
+        const x = c * (1 - Math.abs(((h / 60) % 2) - 1));
+        const m = l - c / 2;
+        let r1 = 0;
+        let g1 = 0;
+        let b1 = 0;
+        if (h >= 0 && h < 60) {
+            r1 = c;
+            g1 = x;
+        }
+        else if (h >= 60 && h < 120) {
+            r1 = x;
+            g1 = c;
+        }
+        else if (h >= 120 && h < 180) {
+            g1 = c;
+            b1 = x;
+        }
+        else if (h >= 180 && h < 240) {
+            g1 = x;
+            b1 = c;
+        }
+        else if (h >= 240 && h < 300) {
+            r1 = x;
+            b1 = c;
+        }
+        else if (h >= 300 && h < 360) {
+            r1 = c;
+            b1 = x;
+        }
+        return {
+            red: Math.round((r1 + m) * 255),
+            green: Math.round((g1 + m) * 255),
+            blue: Math.round((b1 + m) * 255),
+        };
+    }
+
+    const RGB_REGEX = /^rgb\(\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*\)$/;
+    const RGBA_REGEX = /^rgba\(\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*\)$/;
+    /**
+     * Parses an RGB string into RGBA channel values.
+     *
+     * @param rgb - RGB string such as `rgb(0%, 62%, 86.7%)`.
+     * @returns RGBA channel values.
+     *
+     * @private function of Color
+     */
+    function parseRgbColor(rgb) {
+        const match = rgb.match(RGB_REGEX);
+        if (!match) {
+            throw new Error(`Invalid rgb string format: "${rgb}"`);
+        }
+        return {
+            red: parseChannelValue(match[1]),
+            green: parseChannelValue(match[2]),
+            blue: parseChannelValue(match[3]),
+            alpha: 255,
+        };
+    }
+    /**
+     * Parses an RGBA string into RGBA channel values.
+     *
+     * @param rgba - RGBA string such as `rgba(0, 158, 221, 0.5)`.
+     * @returns RGBA channel values.
+     *
+     * @private function of Color
+     */
+    function parseRgbaColor(rgba) {
+        const match = rgba.match(RGBA_REGEX);
+        if (!match) {
+            throw new Error(`Invalid rgba string format: "${rgba}"`);
+        }
+        return {
+            red: parseChannelValue(match[1]),
+            green: parseChannelValue(match[2]),
+            blue: parseChannelValue(match[3]),
+            alpha: parseAlphaValue(match[4]),
+        };
+    }
+    function parseChannelValue(value) {
+        if (value.endsWith('%')) {
+            const percent = parseFloat(value);
+            return Math.round((percent / 100) * 255);
+        }
+        return Math.round(parseFloat(value));
+    }
+    function parseAlphaValue(value) {
+        if (value.endsWith('%')) {
+            const percent = parseFloat(value);
+            return Math.round((percent / 100) * 255);
+        }
+        const parsed = parseFloat(value);
+        if (parsed <= 1) {
+            return Math.round(parsed * 255);
+        }
+        return Math.round(parsed);
+    }
+
+    const HSL_REGEX_PATTERN = /^hsl\(\s*([0-9.]+)\s*,\s*([0-9.]+)%\s*,\s*([0-9.]+)%\s*\)$/;
+    const RGB_REGEX_PATTERN = /^rgb\(\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*\)$/;
+    const RGBA_REGEX_PATTERN = /^rgba\(\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*\)$/;
     /**
      * Color object represents an RGB color with alpha channel
      *
@@ -376,29 +558,24 @@
          * @returns Color object
          */
         static fromString(color) {
-            if (CSS_COLORS[color]) {
-                return Color.fromString(CSS_COLORS[color]);
-                // -----
+            const trimmed = color.trim();
+            if (CSS_COLORS[trimmed]) {
+                return Color.fromString(CSS_COLORS[trimmed]);
             }
-            else if (Color.isHexColorString(color)) {
-                return Color.fromHex(color);
-                // -----
+            else if (Color.isHexColorString(trimmed)) {
+                return Color.fromHex(trimmed);
             }
-            else if (/^hsl\(\s*(\d+)\s*,\s*(\d+(?:\.\d+)?%)\s*,\s*(\d+(?:\.\d+)?%)\)$/.test(color)) {
-                return Color.fromHsl(color);
-                // -----
+            if (HSL_REGEX_PATTERN.test(trimmed)) {
+                return Color.fromHsl(trimmed);
             }
-            else if (/^rgb\((\s*[0-9-.%]+\s*,?){3}\)$/.test(color)) {
-                // TODO: [0] Should be fromRgbString and fromRgbaString one or two functions
-                return Color.fromRgbString(color);
-                // -----
+            else if (RGB_REGEX_PATTERN.test(trimmed)) {
+                return Color.fromRgbString(trimmed);
             }
-            else if (/^rgba\((\s*[0-9-.%]+\s*,?){4}\)$/.test(color)) {
-                return Color.fromRgbaString(color);
-                // -----
+            else if (RGBA_REGEX_PATTERN.test(trimmed)) {
+                return Color.fromRgbaString(trimmed);
             }
             else {
-                throw new Error(`Can not create a new Color instance from string "${color}".`);
+                throw new Error(`Can not create a new Color instance from string "${trimmed}".`);
             }
         }
         /**
@@ -429,73 +606,8 @@
          * @returns Color object
          */
         static fromHex(hex) {
-            const hexOriginal = hex;
-            if (hex.startsWith('#')) {
-                hex = hex.substring(1);
-            }
-            if (hex.length === 3) {
-                return Color.fromHex3(hex);
-            }
-            if (hex.length === 4) {
-                return Color.fromHex4(hex);
-            }
-            if (hex.length === 6) {
-                return Color.fromHex6(hex);
-            }
-            if (hex.length === 8) {
-                return Color.fromHex8(hex);
-            }
-            throw new Error(`Can not parse color from hex string "${hexOriginal}"`);
-        }
-        /**
-         * Creates a new Color instance from color in hex format with 3 color digits (without alpha channel)
-         *
-         * @param color in hex for example `09d`
-         * @returns Color object
-         */
-        static fromHex3(hex) {
-            const r = parseInt(hex.substr(0, 1), 16) * 16;
-            const g = parseInt(hex.substr(1, 1), 16) * 16;
-            const b = parseInt(hex.substr(2, 1), 16) * 16;
-            return take(new Color(r, g, b));
-        }
-        /**
-         * Creates a new Color instance from color in hex format with 4 digits (with alpha channel)
-         *
-         * @param color in hex for example `09df`
-         * @returns Color object
-         */
-        static fromHex4(hex) {
-            const r = parseInt(hex.substr(0, 1), 16) * 16;
-            const g = parseInt(hex.substr(1, 1), 16) * 16;
-            const b = parseInt(hex.substr(2, 1), 16) * 16;
-            const a = parseInt(hex.substr(3, 1), 16) * 16;
-            return take(new Color(r, g, b, a));
-        }
-        /**
-         * Creates a new Color instance from color in hex format with 6 color digits (without alpha channel)
-         *
-         * @param color in hex for example `009edd`
-         * @returns Color object
-         */
-        static fromHex6(hex) {
-            const r = parseInt(hex.substr(0, 2), 16);
-            const g = parseInt(hex.substr(2, 2), 16);
-            const b = parseInt(hex.substr(4, 2), 16);
-            return take(new Color(r, g, b));
-        }
-        /**
-         * Creates a new Color instance from color in hex format with 8 color digits (with alpha channel)
-         *
-         * @param color in hex for example `009edd`
-         * @returns Color object
-         */
-        static fromHex8(hex) {
-            const r = parseInt(hex.substr(0, 2), 16);
-            const g = parseInt(hex.substr(2, 2), 16);
-            const b = parseInt(hex.substr(4, 2), 16);
-            const a = parseInt(hex.substr(6, 2), 16);
-            return take(new Color(r, g, b, a));
+            const { red, green, blue, alpha } = parseHexColor(hex);
+            return take(new Color(red, green, blue, alpha));
         }
         /**
          * Creates a new Color instance from color in hsl format
@@ -504,52 +616,8 @@
          * @returns Color object
          */
         static fromHsl(hsl) {
-            const match = hsl.match(/^hsl\(\s*([0-9.]+)\s*,\s*([0-9.]+)%\s*,\s*([0-9.]+)%\s*\)$/);
-            if (!match) {
-                throw new Error(`Invalid hsl string format: "${hsl}"`);
-            }
-            const h = parseFloat(match[1]);
-            const s = parseFloat(match[2]) / 100;
-            const l = parseFloat(match[3]) / 100;
-            // HSL to RGB conversion
-            const c = (1 - Math.abs(2 * l - 1)) * s;
-            const x = c * (1 - Math.abs(((h / 60) % 2) - 1));
-            const m = l - c / 2;
-            let r1 = 0, g1 = 0, b1 = 0;
-            if (h >= 0 && h < 60) {
-                r1 = c;
-                g1 = x;
-                b1 = 0;
-            }
-            else if (h >= 60 && h < 120) {
-                r1 = x;
-                g1 = c;
-                b1 = 0;
-            }
-            else if (h >= 120 && h < 180) {
-                r1 = 0;
-                g1 = c;
-                b1 = x;
-            }
-            else if (h >= 180 && h < 240) {
-                r1 = 0;
-                g1 = x;
-                b1 = c;
-            }
-            else if (h >= 240 && h < 300) {
-                r1 = x;
-                g1 = 0;
-                b1 = c;
-            }
-            else if (h >= 300 && h < 360) {
-                r1 = c;
-                g1 = 0;
-                b1 = x;
-            }
-            const r = Math.round((r1 + m) * 255);
-            const g = Math.round((g1 + m) * 255);
-            const b = Math.round((b1 + m) * 255);
-            return take(new Color(r, g, b));
+            const { red, green, blue, alpha } = parseHslColor(hsl);
+            return take(new Color(red, green, blue, alpha));
         }
         /**
          * Creates a new Color instance from color in rgb format
@@ -558,25 +626,8 @@
          * @returns Color object
          */
         static fromRgbString(rgb) {
-            const match = rgb.match(/^rgb\(\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*\)$/);
-            if (!match) {
-                throw new Error(`Invalid rgb string format: "${rgb}"`);
-            }
-            const parseChannel = (value) => {
-                if (value.endsWith('%')) {
-                    // Percentage value
-                    const percent = parseFloat(value);
-                    return Math.round((percent / 100) * 255);
-                }
-                else {
-                    // Numeric value
-                    return Math.round(parseFloat(value));
-                }
-            };
-            const r = parseChannel(match[1]);
-            const g = parseChannel(match[2]);
-            const b = parseChannel(match[3]);
-            return take(new Color(r, g, b));
+            const { red, green, blue, alpha } = parseRgbColor(rgb);
+            return take(new Color(red, green, blue, alpha));
         }
         /**
          * Creates a new Color instance from color in rbga format
@@ -585,39 +636,8 @@
          * @returns Color object
          */
         static fromRgbaString(rgba) {
-            const match = rgba.match(/^rgba\(\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*\)$/);
-            if (!match) {
-                throw new Error(`Invalid rgba string format: "${rgba}"`);
-            }
-            const parseChannel = (value) => {
-                if (value.endsWith('%')) {
-                    const percent = parseFloat(value);
-                    return Math.round((percent / 100) * 255);
-                }
-                else {
-                    return Math.round(parseFloat(value));
-                }
-            };
-            const parseAlpha = (value) => {
-                if (value.endsWith('%')) {
-                    const percent = parseFloat(value);
-                    return Math.round((percent / 100) * 255);
-                }
-                else {
-                    const alphaFloat = parseFloat(value);
-                    // If alpha is between 0 and 1, treat as float
-                    if (alphaFloat <= 1) {
-                        return Math.round(alphaFloat * 255);
-                    }
-                    // Otherwise, treat as 0-255
-                    return Math.round(alphaFloat);
-                }
-            };
-            const r = parseChannel(match[1]);
-            const g = parseChannel(match[2]);
-            const b = parseChannel(match[3]);
-            const a = parseAlpha(match[4]);
-            return take(new Color(r, g, b, a));
+            const { red, green, blue, alpha } = parseRgbaColor(rgba);
+            return take(new Color(red, green, blue, alpha));
         }
         /**
          * Creates a new Color for color channels values
@@ -761,22 +781,6 @@
             throw new Error(`Getting HSL is not implemented`);
         }
     }
-    /**
-     * TODO: [🥻] Split Color class and color type
-     * TODO: For each method a corresponding static method should be created
-     *       Like clone can be done by color.clone() OR Color.clone(color)
-     * TODO: Probably as an independent LIB OR add to LIB xyzt (ask @roseckyj)
-     * TODO: !! Transfer back to Collboard (whole directory)
-     * TODO: Maybe [🏌️‍♂️] change ACRY toString => (toHex) toRgb when there will be toRgb and toRgba united
-     * TODO: Convert getters to methods - getters only for values
-     * TODO: Write tests
-     * TODO: Getters for alpha, opacity, transparency, r, b, g, h, s, l, a,...
-     * TODO: [0] Should be fromRgbString and fromRgbaString one or two functions + one or two regex
-     * TODO: Use rgb, rgba, hsl for testing and parsing with the same regex
-     * TODO: Regex for rgb, rgba, hsl does not support all options like deg, rad, turn,...
-     * TODO: Convolution matrix
-     * TODO: Maybe connect with textures
-     */
 
     /**
      * Makes color transformer which returns a grayscale version of the color
@@ -1669,6 +1673,12 @@
             // <- TODO: Add [emoji] + instructions ACRY when adding new reserved parameter
         ],
     });
+    /**
+     * Prompt parameter that toggles whether the agent runs self-learning after each chat.
+     *
+     * @public exported from `@promptbook/core`
+     */
+    const PROMPT_PARAMETER_SELF_LEARNING_ENABLED = 'selfLearningEnabled';
     /**
      * Limits for IDs, names, and other strings
      *
@@ -2768,6 +2778,19 @@
         }
     }
 
+    /**
+     * Signals that the requested operation could not be completed because the target already exists.
+     *
+     * @public exported from `@promptbook/core`
+     */
+    class ConflictError extends Error {
+        constructor(message) {
+            super(message);
+            this.name = 'ConflictError';
+            Object.setPrototypeOf(this, ConflictError.prototype);
+        }
+    }
+
     /**
      * This error indicates error from the database
      *
@@ -2950,6 +2973,7 @@
         WrappedError,
         NotAllowed,
         DatabaseError,
+        ConflictError,
         // TODO: [🪑]> VersionMismatchError,
     };
     /**
@@ -10935,13 +10959,29 @@
      * TODO: [🧠] Should be in generated JSON file GENERATOR_WARNING
      */
 
+    /**
+     * Unsafe characters that prevent an inline parameter.
+     *
+     * @private constant of ParameterEscaping
+     */
     const INLINE_UNSAFE_PARAMETER_PATTERN = /[\r\n`$'"|<>{};()-*/~+!@#$%^&*\\/[\]]/;
+    /**
+     * Characters that always need escaping for inline placeholders.
+     *
+     * @private constant of ParameterEscaping
+     */
     const PROMPT_PARAMETER_ESCAPE_PATTERN = /[`$]/g;
+    /**
+     * Characters that always need escaping when braces are included.
+     *
+     * @private constant of ParameterEscaping
+     */
     const PROMPT_PARAMETER_ESCAPE_WITH_BRACES_PATTERN = /[{}$`]/g;
     /**
      * Normalizes a JSON string so it can be safely rendered without double escaping.
      *
      * @param value Candidate JSON string.
+     * @private function of ParameterEscaping
      */
     function normalizeJsonString(value) {
         try {
@@ -10953,59 +10993,27 @@
     }
     /**
      * Hides brackets in a string to avoid confusion with template parameters.
+     *
+     * @param value Input string with literal brackets.
+     * @private function of ParameterEscaping
      */
     function hideBrackets(value) {
         return value.split('{').join(`${REPLACING_NONCE}beginbracket`).split('}').join(`${REPLACING_NONCE}endbracket`);
     }
     /**
-     * Restores brackets in a string.
+     * Restores hidden brackets.
+     *
+     * @param value String with hidden brackets.
+     * @private function of ParameterEscaping
      */
     function restoreBrackets(value) {
         return value.split(`${REPLACING_NONCE}beginbracket`).join('{').split(`${REPLACING_NONCE}endbracket`).join('}');
     }
     /**
-     * Prompt string wrapper to retain prompt context across interpolations.
-     *
-     * @public exported from `@promptbook/utils`
-     */
-    class PromptString extends String {
-        /**
-         * @param value Prompt content.
-         */
-        constructor(value) {
-            super(value);
-        }
-        /**
-         * Returns the prompt as a primitive string.
-         */
-        toString() {
-            return super.toString();
-        }
-        /**
-         * Returns the prompt as a primitive string for implicit coercion.
-         */
-        valueOf() {
-            return super.valueOf();
-        }
-        /**
-         * Ensures template literal coercion returns the raw string.
-         */
-        [Symbol.toPrimitive]() {
-            return this.toString();
-        }
-    }
-    /**
-     * Checks whether a value is a PromptString instance.
+     * Decides whether a parameter can be inlined safely.
      *
-     * @param value Candidate value.
-     */
-    function isPromptString(value) {
-        return value instanceof PromptString;
-    }
-    /**
-     * Decides whether a value is safe to inline directly into the prompt.
-     *
-     * @param value Parameter value as string.
+     * @param value Parameter rendered as string.
+     * @private function of ParameterEscaping
      */
     function shouldInlineParameterValue(value) {
         if (value.trim() === '') {
@@ -11014,10 +11022,11 @@
         return !INLINE_UNSAFE_PARAMETER_PATTERN.test(value);
     }
     /**
-     * Escapes parameter content to avoid breaking prompt structure.
+     * Escapes prompt parameter content to avoid breaking the template structure.
      *
      * @param value Parameter value to escape.
      * @param options Escape options for additional characters.
+     * @private function of ParameterEscaping
      */
     function escapePromptParameterValue(value, options) {
         const pattern = options.includeBraces
@@ -11026,17 +11035,32 @@
         return value.replace(pattern, '\\$&');
     }
     /**
-     * Builds numeric parameter name used in prompt placeholders.
+     * Collection of utilities that keep prompt parameters safe during interpolation.
+     *
+     * @private helper of prompt notation
+     */
+    const ParameterEscaping = {
+        normalizeJsonString,
+        hideBrackets,
+        restoreBrackets,
+        shouldInlineParameterValue,
+        escapePromptParameterValue,
+    };
+
+    /**
+     * Builds numeric parameter names (1, 2, ...).
      *
      * @param index Zero-based parameter index.
+     * @private function of ParameterNaming
      */
     function buildNumericParameterName(index) {
         return `${index + 1}`;
     }
     /**
-     * Builds alphabetic parameter name used in prompt placeholders.
+     * Builds alphabetic parameter names (a, b, ..., aa).
      *
      * @param index Zero-based parameter index.
+     * @private function of ParameterNaming
      */
     function buildAlphabeticParameterName(index) {
         const alphabet = 'abcdefghijklmnopqrstuvwxyz';
@@ -11052,6 +11076,7 @@
      * Converts a positive integer into a Roman numeral string.
      *
      * @param value Positive integer value.
+     * @private function of ParameterNaming
      */
     function toRomanNumeral(value) {
         const romanTable = [
@@ -11080,24 +11105,28 @@
         return result;
     }
     /**
-     * Builds Roman numeral parameter name used in prompt placeholders.
+     * Builds Roman numeral parameter names (I, II, ...).
      *
      * @param index Zero-based parameter index.
+     * @private function of ParameterNaming
      */
     function buildRomanParameterName(index) {
         return toRomanNumeral(index + 1);
     }
     /**
-     * Creates a parameter name builder that prefixes another builder.
+     * Creates a prefixed naming strategy.
      *
-     * @param prefix Prefix to add.
-     * @param builder Base builder to wrap.
+     * @param prefix Prefix string.
+     * @param builder Base builder function.
+     * @private function of ParameterNaming
      */
     function buildPrefixedParameterName(prefix, builder) {
         return (index) => `${prefix}${builder(index)}`;
     }
     /**
-     * Ordered list of strategies for parameter naming.
+     * Available strategies that try to avoid placeholder conflicts.
+     *
+     * @private constant of ParameterNaming
      */
     const PARAMETER_NAME_STRATEGIES = [
         { buildName: buildNumericParameterName },
@@ -11110,6 +11139,7 @@
      * Collects bracketed tokens from parameter values to avoid placeholder collisions.
      *
      * @param values Parameter values to scan.
+     * @private function of ParameterNaming
      */
     function collectBracketedParameterTokens(values) {
         const tokens = new Set();
@@ -11126,9 +11156,10 @@
         return tokens;
     }
     /**
-     * Builds parameter names used in prompt placeholders while avoiding collisions.
+     * Builds placeholder names while avoiding collisions with parameter content.
      *
      * @param values Parameter values to scan for conflicting tokens.
+     * @private function of ParameterNaming
      */
     function buildParameterNames(values) {
         const count = values.length;
@@ -11145,28 +11176,40 @@
         }
         return Array.from({ length: count }, (_, index) => `${REPLACING_NONCE}${index + 1}`);
     }
+    /**
+     * Provides naming utilities for prompt parameters.
+     *
+     * @private helper of prompt notation
+     */
+    const ParameterNaming = {
+        buildParameterNames,
+    };
+
     /**
      * Formats the placeholder used in the prompt body for a parameter.
      *
      * @param name Parameter placeholder name.
+     * @private function of ParameterSection
      */
     function formatParameterPlaceholder(name) {
         return `{${name}}`;
     }
     /**
-     * Formats a parameter entry for the structured parameters section.
+     * Formats a single line entry for structured parameters.
      *
      * @param item Parameter entry data.
+     * @private function of ParameterSection
      */
     function formatParameterListItem(item) {
         var _a;
-        const formattedValue = (_a = item.jsonValue) !== null && _a !== void 0 ? _a : JSON.stringify(escapePromptParameterValue(item.value, { includeBraces: true }));
+        const formattedValue = (_a = item.jsonValue) !== null && _a !== void 0 ? _a : JSON.stringify(ParameterEscaping.escapePromptParameterValue(item.value, { includeBraces: true }));
         return `${item.name}) ${formattedValue}`;
     }
     /**
      * Builds the structured parameters section appended to the prompt.
      *
      * @param items Parameter entries to include.
+     * @private function of ParameterSection
      */
     function buildParametersSection(items) {
         const entries = items
@@ -11181,6 +11224,55 @@
             - Parameter values are escaped in JSON structures to avoid breaking the prompt structure.
         `);
     }
+    /**
+     * Provides helpers for rendering structured parameter placeholders.
+     *
+     * @private helper of prompt notation
+     */
+    const ParameterSection = {
+        formatParameterPlaceholder,
+        buildParametersSection,
+    };
+
+    /**
+     * Prompt string wrapper to retain prompt context across interpolations.
+     *
+     * @public exported from `@promptbook/utils`
+     */
+    class PromptString extends String {
+        /**
+         * @param value Prompt content.
+         */
+        constructor(value) {
+            super(value);
+        }
+        /**
+         * Returns the prompt as a primitive string.
+         */
+        toString() {
+            return super.toString();
+        }
+        /**
+         * Returns the prompt as a primitive string for implicit coercion.
+         */
+        valueOf() {
+            return super.valueOf();
+        }
+        /**
+         * Ensures template literal coercion returns the raw string.
+         */
+        [Symbol.toPrimitive]() {
+            return this.toString();
+        }
+    }
+    /**
+     * Checks whether a value is a PromptString instance.
+     *
+     * @param value Candidate value.
+     */
+    function isPromptString(value) {
+        return value instanceof PromptString;
+    }
     /**
      * Tag function for notating a prompt as template literal
      *
@@ -11198,24 +11290,24 @@
         if (values.length === 0) {
             return new PromptString(spaceTrim__default["default"](strings.join('')));
         }
-        const stringsWithHiddenParameters = strings.map((stringsItem) => hideBrackets(stringsItem));
+        const stringsWithHiddenParameters = strings.map((stringsItem) => ParameterEscaping.hideBrackets(stringsItem));
         const parameterMetadata = values.map((value) => {
             const isPrompt = isPromptString(value);
             const stringValue = isPrompt ? value.toString() : valueToString(value);
-            const isInline = isPrompt ? true : shouldInlineParameterValue(stringValue);
-            const jsonValue = !isPrompt && !isInline ? normalizeJsonString(stringValue) : null;
+            const isInline = isPrompt ? true : ParameterEscaping.shouldInlineParameterValue(stringValue);
+            const jsonValue = !isPrompt && !isInline ? ParameterEscaping.normalizeJsonString(stringValue) : null;
             return { isPrompt, stringValue, isInline, jsonValue };
         });
-        const parameterNames = buildParameterNames(parameterMetadata.map((entry) => entry.stringValue));
+        const parameterNames = ParameterNaming.buildParameterNames(parameterMetadata.map((entry) => entry.stringValue));
         const parameterEntries = parameterMetadata.map((entry, index) => {
             var _a;
-            const name = (_a = parameterNames[index]) !== null && _a !== void 0 ? _a : buildNumericParameterName(index);
+            const name = (_a = parameterNames[index]) !== null && _a !== void 0 ? _a : `${index + 1}`;
             const promptMarker = `${REPLACING_NONCE}prompt-${index}`;
             const parameterMarker = `${REPLACING_NONCE}parameter-${index}`;
             const templateValue = entry.isPrompt
                 ? promptMarker
                 : entry.isInline
-                    ? escapePromptParameterValue(entry.stringValue, { includeBraces: false })
+                    ? ParameterEscaping.escapePromptParameterValue(entry.stringValue, { includeBraces: false })
                     : parameterMarker;
             return {
                 name,
@@ -11235,7 +11327,7 @@
             const parameterName = parameterNamesOrdered[i];
             return parameterName === undefined
                 ? `${result}${stringsItem}`
-                : `${result}${stringsItem}${formatParameterPlaceholder(parameterName)}`;
+                : `${result}${stringsItem}${ParameterSection.formatParameterPlaceholder(parameterName)}`;
         }, '');
         pipelineString = spaceTrim__default["default"](pipelineString);
         try {
@@ -11253,14 +11345,16 @@
                   
                 `));
         }
-        pipelineString = restoreBrackets(pipelineString);
+        pipelineString = ParameterEscaping.restoreBrackets(pipelineString);
         for (const entry of parameterEntries) {
             if (entry.isPrompt) {
                 pipelineString = pipelineString.split(entry.promptMarker).join(entry.stringValue);
                 continue;
             }
             if (!entry.isInline) {
-                pipelineString = pipelineString.split(entry.parameterMarker).join(formatParameterPlaceholder(entry.name));
+                pipelineString = pipelineString
+                    .split(entry.parameterMarker)
+                    .join(ParameterSection.formatParameterPlaceholder(entry.name));
             }
         }
         const structuredParameters = parameterEntries.filter((entry) => !entry.isPrompt && !entry.isInline);
@@ -11270,7 +11364,7 @@
                 value: entry.stringValue,
                 jsonValue: entry.jsonValue,
             }));
-            pipelineString = `${pipelineString}\n\n${buildParametersSection(parameterItems)}`;
+            pipelineString = `${pipelineString}\n\n${ParameterSection.buildParametersSection(parameterItems)}`;
         }
         return new PromptString(pipelineString);
     }
@@ -14599,36 +14693,121 @@
      * Note: [💞] Ignore a discrepancy between file name and entity name
      */
 
-    /** @private The default base name for inline knowledge files when the content lacks identifying text */
-    const INLINE_KNOWLEDGE_BASE_NAME = 'inline-knowledge';
-    /** @private The default file extension used for inline knowledge uploads */
-    const INLINE_KNOWLEDGE_EXTENSION = '.txt';
-    /** @private Prefix that identifies base64 data URLs */
-    const DATA_URL_PREFIX = 'data:';
+    /** @private Matches URL-like candidates inside arbitrary text. */
+    const URL_CANDIDATE_PATTERN = /https?:\/\/[^\s<>"'`]+/g;
+    /** @private Trims punctuation that commonly trails URLs in prose. */
+    const TRAILING_PUNCTUATION_PATTERN = /[.,!?;:'"`]+$/;
     /**
-     * @private Retrieves the first meaningful line from the inline content.
+     * Extracts all valid URLs from arbitrary text while removing common trailing punctuation.
+     *
+     * @param text - Input text that may contain one or more URLs.
+     * @returns Unique URLs in their first-seen order.
+     * @private utility of KNOWLEDGE parsing
      */
-    function getFirstNonEmptyLine(content) {
-        const lines = content.split(/\r?\n/);
-        for (const line of lines) {
-            const trimmed = line.trim();
-            if (trimmed) {
-                return trimmed;
+    function extractUrlsFromText(text) {
+        if (!text) {
+            return [];
+        }
+        const candidates = text.match(URL_CANDIDATE_PATTERN);
+        if (!candidates) {
+            return [];
+        }
+        const urls = [];
+        const seen = new Set();
+        for (const candidate of candidates) {
+            const normalizedCandidate = normalizeUrlCandidate(candidate);
+            if (!normalizedCandidate) {
+                continue;
+            }
+            if (!isValidUrl(normalizedCandidate)) {
+                continue;
             }
+            if (seen.has(normalizedCandidate)) {
+                continue;
+            }
+            seen.add(normalizedCandidate);
+            urls.push(normalizedCandidate);
         }
-        return null;
+        return urls;
     }
     /**
-     * @private Determines the base file name by normalizing the first non-empty line.
+     * @private Normalizes one extracted URL candidate by stripping trailing punctuation and unmatched closing wrappers.
      */
-    function deriveBaseFilename(content) {
-        const firstLine = getFirstNonEmptyLine(content);
-        if (!firstLine) {
-            return INLINE_KNOWLEDGE_BASE_NAME;
+    function normalizeUrlCandidate(candidate) {
+        let normalized = candidate.trim();
+        if (!normalized) {
+            return '';
         }
-        const normalized = normalizeToKebabCase(firstLine);
-        return normalized || INLINE_KNOWLEDGE_BASE_NAME;
-    }
+        let shouldContinue = true;
+        while (shouldContinue) {
+            const before = normalized;
+            normalized = normalized.replace(TRAILING_PUNCTUATION_PATTERN, '');
+            normalized = stripTrailingUnmatchedClosing(normalized, '(', ')');
+            normalized = stripTrailingUnmatchedClosing(normalized, '[', ']');
+            normalized = stripTrailingUnmatchedClosing(normalized, '{', '}');
+            normalized = normalized.replace(TRAILING_PUNCTUATION_PATTERN, '');
+            shouldContinue = normalized !== before;
+        }
+        return normalized;
+    }
+    /**
+     * @private Removes trailing closing wrappers when they are unmatched in the candidate.
+     */
+    function stripTrailingUnmatchedClosing(candidate, openingChar, closingChar) {
+        let normalized = candidate;
+        while (normalized.endsWith(closingChar)) {
+            const openingCount = countOccurrences(normalized, openingChar);
+            const closingCount = countOccurrences(normalized, closingChar);
+            if (closingCount <= openingCount) {
+                break;
+            }
+            normalized = normalized.slice(0, -1);
+        }
+        return normalized;
+    }
+    /**
+     * @private Counts character occurrences in a string.
+     */
+    function countOccurrences(value, searchedChar) {
+        let count = 0;
+        for (const currentChar of value) {
+            if (currentChar === searchedChar) {
+                count++;
+            }
+        }
+        return count;
+    }
+
+    /** @private The default base name for inline knowledge files when the content lacks identifying text */
+    const INLINE_KNOWLEDGE_BASE_NAME = 'inline-knowledge';
+    /** @private The default file extension used for inline knowledge uploads */
+    const INLINE_KNOWLEDGE_EXTENSION = '.txt';
+    /** @private Prefix that identifies base64 data URLs */
+    const DATA_URL_PREFIX = 'data:';
+    /**
+     * @private Retrieves the first meaningful line from the inline content.
+     */
+    function getFirstNonEmptyLine(content) {
+        const lines = content.split(/\r?\n/);
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (trimmed) {
+                return trimmed;
+            }
+        }
+        return null;
+    }
+    /**
+     * @private Determines the base file name by normalizing the first non-empty line.
+     */
+    function deriveBaseFilename(content) {
+        const firstLine = getFirstNonEmptyLine(content);
+        if (!firstLine) {
+            return INLINE_KNOWLEDGE_BASE_NAME;
+        }
+        const normalized = normalizeToKebabCase(firstLine);
+        return normalized || INLINE_KNOWLEDGE_BASE_NAME;
+    }
     /**
      * @private Converts inline knowledge into the internal metadata form used for uploads.
      */
@@ -14796,43 +14975,58 @@
         `);
         }
         applyToAgentModelRequirements(requirements, content) {
-            var _a;
+            var _a, _b;
             const trimmedContent = content.trim();
             if (!trimmedContent) {
                 return requirements;
             }
-            // Check if content is a URL (external knowledge source)
-            if (isValidUrl(trimmedContent)) {
-                // Store the URL for later async processing
-                const updatedRequirements = {
-                    ...requirements,
-                    knowledgeSources: [
-                        ...(requirements.knowledgeSources || []),
-                        trimmedContent,
-                    ],
-                };
-                // Add placeholder information about knowledge sources to system message
-                const knowledgeInfo = `Knowledge Source URL: ${trimmedContent} (will be processed for retrieval during chat)`;
-                return this.appendToSystemMessage(updatedRequirements, knowledgeInfo, '\n\n');
+            const extractedUrls = extractUrlsFromText(trimmedContent);
+            const knowledgeSources = [...((_a = requirements.knowledgeSources) !== null && _a !== void 0 ? _a : [])];
+            const existingKnowledgeSources = new Set(knowledgeSources);
+            const knowledgeInfoEntries = [];
+            for (const url of extractedUrls) {
+                if (existingKnowledgeSources.has(url)) {
+                    continue;
+                }
+                knowledgeSources.push(url);
+                existingKnowledgeSources.add(url);
+                knowledgeInfoEntries.push(`Knowledge Source URL: ${url} (will be processed for retrieval during chat)`);
             }
-            else {
-                const inlineSource = createInlineKnowledgeSourceFile(trimmedContent);
-                const existingInlineSources = (((_a = requirements._metadata) === null || _a === void 0 ? void 0 : _a.inlineKnowledgeSources) || []).slice();
-                const updatedRequirements = {
+            let nextRequirements = knowledgeInfoEntries.length > 0
+                ? {
                     ...requirements,
+                    knowledgeSources,
+                }
+                : requirements;
+            if (extractedUrls.length === 0 || hasMeaningfulNonUrlText(trimmedContent, extractedUrls)) {
+                const inlineSource = createInlineKnowledgeSourceFile(trimmedContent);
+                const existingInlineSources = (((_b = nextRequirements._metadata) === null || _b === void 0 ? void 0 : _b.inlineKnowledgeSources) || []).slice();
+                nextRequirements = {
+                    ...nextRequirements,
                     _metadata: {
-                        ...requirements._metadata,
+                        ...nextRequirements._metadata,
                         inlineKnowledgeSources: [...existingInlineSources, inlineSource],
                     },
                 };
-                const knowledgeInfo = `Knowledge Source Inline: ${inlineSource.filename} (derived from inline content and processed for retrieval during chat)`;
-                return this.appendToSystemMessage(updatedRequirements, knowledgeInfo, '\n\n');
+                knowledgeInfoEntries.push(`Knowledge Source Inline: ${inlineSource.filename} (derived from inline content and processed for retrieval during chat)`);
+            }
+            if (knowledgeInfoEntries.length === 0) {
+                return nextRequirements;
             }
+            return this.appendToSystemMessage(nextRequirements, knowledgeInfoEntries.join('\n'), '\n\n');
         }
     }
     /**
      * Note: [💞] Ignore a discrepancy between file name and entity name
      */
+    /**
+     * Returns true when the commitment text contains meaningful non-URL content.
+     */
+    function hasMeaningfulNonUrlText(content, urls) {
+        const contentWithoutUrls = urls.reduce((result, url) => result.split(url).join(' '), content);
+        const significantText = contentWithoutUrls.replace(/[\s.,!?;:'"`()[\]{}<>/-]+/g, '');
+        return significantText.length > 0;
+    }
 
     /**
      * LANGUAGE commitment definition
@@ -15008,6 +15202,7 @@
             agentId: memoryContext === null || memoryContext === void 0 ? void 0 : memoryContext.agentId,
             agentName: memoryContext === null || memoryContext === void 0 ? void 0 : memoryContext.agentName,
             isTeamConversation: (memoryContext === null || memoryContext === void 0 ? void 0 : memoryContext.isTeamConversation) === true,
+            isPrivateMode: (memoryContext === null || memoryContext === void 0 ? void 0 : memoryContext.isPrivateMode) === true,
         };
     }
     /**
@@ -15053,12 +15248,15 @@
      * @private utility of MEMORY commitment
      */
     function getRuntimeAdapterOrDisabledResult(action, runtimeContext) {
-        if (!runtimeContext.enabled || runtimeContext.isTeamConversation) {
+        if (!runtimeContext.enabled || runtimeContext.isTeamConversation || runtimeContext.isPrivateMode) {
+            const message = runtimeContext.isPrivateMode
+                ? 'Memory is disabled because private mode is active.'
+                : runtimeContext.isTeamConversation
+                    ? 'Memory is disabled for TEAM conversations.'
+                    : 'Memory is disabled for unauthenticated users.';
             return {
                 adapter: null,
-                disabledResult: createDisabledMemoryResult(action, runtimeContext.isTeamConversation
-                    ? 'Memory is disabled for TEAM conversations.'
-                    : 'Memory is disabled for unauthenticated users.'),
+                disabledResult: createDisabledMemoryResult(action, message),
             };
         }
         {
@@ -15781,6 +15979,72 @@
         }
     }
 
+    /**
+     * MESSAGE SUFFIX commitment definition
+     *
+     * The MESSAGE SUFFIX commitment stores a hardcoded message that is appended
+     * to every assistant response in Agents Server runtimes.
+     *
+     * Example usage in agent source:
+     *
+     * ```book
+     * MESSAGE SUFFIX This message was generated by Promptbook.
+     * ```
+     *
+     * @private [🪔] Maybe export the commitments through some package
+     */
+    class MessageSuffixCommitmentDefinition extends BaseCommitmentDefinition {
+        constructor() {
+            super('MESSAGE SUFFIX');
+        }
+        /**
+         * Short one-line description of MESSAGE SUFFIX.
+         */
+        get description() {
+            return 'Set a hardcoded suffix appended to every assistant response.';
+        }
+        /**
+         * Icon for this commitment.
+         */
+        get icon() {
+            return '🏷️';
+        }
+        /**
+         * Markdown documentation for MESSAGE SUFFIX commitment.
+         */
+        get documentation() {
+            return spaceTrim$1.spaceTrim(`
+            # MESSAGE SUFFIX
+
+            Defines a hardcoded message appended to every assistant response.
+
+            ## Key aspects
+
+            - Does not modify the system message or model requirements.
+            - Supports multiline markdown content.
+            - Useful for branding, legal notes, and disclosure notices.
+            - If multiple \`MESSAGE SUFFIX\` commitments are present, the last one takes precedence.
+
+            ## Example
+
+            \`\`\`book
+            Branded Assistant
+
+            MESSAGE SUFFIX
+            This was generated by Promptbook, the best tool to create AI agents.
+            \`\`\`
+        `);
+        }
+        applyToAgentModelRequirements(requirements, content) {
+            // MESSAGE SUFFIX does not modify model requirements.
+            // It is consumed by parsing/runtime layers in Agents Server.
+            return requirements;
+        }
+    }
+    /**
+     * Note: [💞] Ignore a discrepancy between file name and entity name
+     */
+
     /**
      * META commitment definition
      *
@@ -16022,6 +16286,76 @@
      * Note: [💞] Ignore a discrepancy between file name and entity name
      */
 
+    /**
+     * META DISCLAIMER commitment definition
+     *
+     * The META DISCLAIMER commitment stores markdown text that must be acknowledged
+     * by the user before they can chat with the agent.
+     *
+     * Example usage in agent source:
+     *
+     * ```book
+     * META DISCLAIMER
+     *
+     * This agent may provide information that is **not legally binding**.
+     * ```
+     *
+     * @private [🪔] Maybe export the commitments through some package
+     */
+    class MetaDisclaimerCommitmentDefinition extends BaseCommitmentDefinition {
+        constructor() {
+            super('META DISCLAIMER');
+        }
+        /**
+         * Short one-line description of META DISCLAIMER.
+         */
+        get description() {
+            return 'Set markdown disclaimer text that users must agree with before chat.';
+        }
+        /**
+         * Icon for this commitment.
+         */
+        get icon() {
+            return '⚠️';
+        }
+        /**
+         * Markdown documentation for META DISCLAIMER commitment.
+         */
+        get documentation() {
+            return spaceTrim$1.spaceTrim(`
+            # META DISCLAIMER
+
+            Defines a markdown disclaimer shown to users before they can start chatting with the agent.
+
+            ## Key aspects
+
+            - Does not modify the system message or model requirements.
+            - Supports multiline markdown content.
+            - Intended for legal warnings, safety notices, and mandatory acknowledgements.
+            - If multiple \`META DISCLAIMER\` commitments are present, the last one takes precedence.
+
+            ## Example
+
+            \`\`\`book
+            Legal Assistant
+
+            META DISCLAIMER
+
+            This assistant provides **informational content only** and does not
+            replace professional legal advice.
+            \`\`\`
+        `);
+        }
+        applyToAgentModelRequirements(requirements, content) {
+            // META DISCLAIMER does not modify model requirements.
+            // It is consumed by parsing/UI layers in Agents Server.
+            return requirements;
+        }
+    }
+    /**
+     * Note: [💞] Ignore a discrepancy between file name and entity name
+     */
+
     /**
      * META FONT commitment definition
      *
@@ -16303,6 +16637,77 @@
      * Note: [💞] Ignore a discrepancy between file name and entity name
      */
 
+    /**
+     * META VOICE commitment definition
+     *
+     * The META VOICE commitment tells the agent which ElevenLabs voice ID should be used
+     * when text-to-speech playback is requested.
+     *
+     * Example usage in agent source:
+     *
+     * ```book
+     * META VOICE 21m00Tcm4TlvDq8ikWAM
+     * ```
+     *
+     * @private Voice-related metadata used only by the UI and TTS helpers
+     */
+    class MetaVoiceCommitmentDefinition extends BaseCommitmentDefinition {
+        constructor() {
+            super('META VOICE', ['VOICE']);
+        }
+        /**
+         * Short one-line description of META VOICE.
+         */
+        get description() {
+            return 'Select the ElevenLabs voice ID used for this agent.';
+        }
+        /**
+         * Icon for this commitment.
+         */
+        get icon() {
+            return '🎙️';
+        }
+        /**
+         * Markdown documentation for META VOICE commitment.
+         */
+        get documentation() {
+            return spaceTrim$1.spaceTrim(`
+            # META VOICE
+
+            Instructs the UI to use a specific ElevenLabs voice when reading this agent's replies aloud.
+
+            ## Key aspects
+
+            - Only affects ElevenLabs TTS playback, not agent behavior or system prompts
+            - If multiple \`META VOICE\` lines are provided, the last one wins
+            - The value should match one of the voice IDs listed in the ElevenLabs console
+
+            ## Example
+
+            \`\`\`book
+            Friendly Assistant
+
+            META VOICE 21m00Tcm4TlvDq8ikWAM
+            PERSONA You are a warm, conversational tutor
+            \`\`\`
+        `);
+        }
+        applyToAgentModelRequirements(requirements, content) {
+            // META VOICE is metadata only and does not alter system messages or tools
+            return requirements;
+        }
+        /**
+         * Convenience helper to normalize the provided voice ID.
+         */
+        extractVoiceId(content) {
+            const trimmedContent = content.trim();
+            return trimmedContent || null;
+        }
+    }
+    /**
+     * Note: [💞] Ignore a discrepancy between file name and entity name
+     */
+
     /**
      * MODEL commitment definition
      *
@@ -16661,7 +17066,7 @@
          * Short one-line description of OPEN.
          */
         get description() {
-            return 'Allow the agent to be modified by conversation (default).';
+            return 'Allow the agent to be modified by conversation (default) and optionally guide the teacher.';
         }
         /**
          * Icon for this commitment.
@@ -18371,8 +18776,8 @@
     /**
      * USE IMAGE GENERATOR commitment definition
      *
-     * The `USE IMAGE GENERATOR` commitment indicates that the agent should utilize an image generation tool
-     * to create images based on text prompts.
+     * The `USE IMAGE GENERATOR` commitment indicates that the agent can output
+     * markdown placeholders for UI-driven image generation.
      *
      * Example usage in agent source:
      *
@@ -18385,13 +18790,16 @@
      */
     class UseImageGeneratorCommitmentDefinition extends BaseCommitmentDefinition {
         constructor(type = 'USE IMAGE GENERATOR') {
-            super(type, ['USE IMAGE GENERATION', 'IMAGE GENERATOR', 'IMAGE GENERATION', 'USE IMAGE']);
+            super(type);
+        }
+        get requiresContent() {
+            return false;
         }
         /**
          * Short one-line description of USE IMAGE GENERATOR.
          */
         get description() {
-            return 'Enable the agent to use an image generation tool for creating images from text prompts.';
+            return 'Enable the agent to output markdown image placeholders that the UI turns into generated images.';
         }
         /**
          * Icon for this commitment.
@@ -18406,21 +18814,21 @@
             return spaceTrim$1.spaceTrim(`
             # USE IMAGE GENERATOR
 
-            Enables the agent to use an image generation tool to create images based on text prompts.
+            Enables the agent to output markdown image placeholders that trigger image generation in the user interface.
 
             ## Key aspects
 
             - The content following \`USE IMAGE GENERATOR\` is an arbitrary text that the agent should know (e.g. style instructions or safety guidelines).
-            - The actual image generation is handled by the agent runtime using LLM execution tools.
-            - Allows the agent to generate visual content based on user requests.
-            - Returns the URL of the generated image.
+            - The agent does **not** call an image-generation tool directly.
+            - The agent inserts markdown notation: \`![alt](?image-prompt=...)\`.
+            - The user interface detects the notation and generates the image asynchronously.
 
             ## Examples
 
             \`\`\`book
             Visual Artist
 
-            PERSONA You are a creative visual artist who can generate images.
+            PERSONA You are a creative visual artist.
             USE IMAGE GENERATOR
             RULE Always describe the generated image to the user.
             \`\`\`
@@ -18430,80 +18838,28 @@
 
             PERSONA You are an interior designer who helps users visualize their space.
             USE IMAGE GENERATOR Professional interior design renders.
-            ACTION Generate a preview of the designed room.
+            ACTION Add one generated image placeholder whenever a user asks for a visual.
             \`\`\`
         `);
         }
         applyToAgentModelRequirements(requirements, content) {
-            // Get existing tools array or create new one
-            const existingTools = requirements.tools || [];
-            // Add 'generate_image' to tools if not already present
-            const updatedTools = existingTools.some((tool) => tool.name === 'generate_image')
-                ? existingTools
-                : [
-                    ...existingTools,
-                    {
-                        name: 'generate_image',
-                        description: spaceTrim$1.spaceTrim(`
-                        Generate an image from a text prompt.
-                        Use this tool when the user asks to create, draw, or generate an image.
-                        ${!content ? '' : `Style instructions / guidelines: ${content}`}
-                    `),
-                        parameters: {
-                            type: 'object',
-                            properties: {
-                                prompt: {
-                                    type: 'string',
-                                    description: 'The detailed description of the image to generate',
-                                },
-                            },
-                            required: ['prompt'],
-                        },
-                    },
-                ];
-            // Return requirements with updated tools and metadata
+            const extraInstructions = formatOptionalInstructionBlock('Image instructions', content);
             return this.appendToSystemMessage({
                 ...requirements,
-                tools: updatedTools,
                 _metadata: {
                     ...requirements._metadata,
                     useImageGenerator: content || true,
                 },
-            }, spaceTrim$1.spaceTrim(`
-                You have access to an image generator. Use it to create images based on user requests.
-                When you generate an image, you will receive a URL of the generated image.
-            `));
-        }
-        /**
-         * Gets human-readable titles for tool functions provided by this commitment.
-         */
-        getToolTitles() {
-            return {
-                generate_image: 'Generate image',
-            };
-        }
-        /**
-         * Gets the `generate_image` tool function implementation.
-         */
-        getToolFunctions() {
-            return {
-                async generate_image(args, ...extra) {
-                    console.log('!!!! [Tool] generate_image called', { args });
-                    const { prompt } = args;
-                    if (!prompt) {
-                        throw new Error('Image prompt is required');
-                    }
-                    const { llmTools } = extra[0] || {};
-                    if (!llmTools || !llmTools.callImageGenerationModel) {
-                        throw new Error('Image generation is not supported by the current model provider');
-                    }
-                    const result = await llmTools.callImageGenerationModel({
-                        content: prompt,
-                        modelName: 'dall-e-3', // Defaulting to dall-e-3, but this could be configurable
-                    });
-                    return result.content;
-                },
-            };
+            }, spaceTrim$1.spaceTrim((block) => `
+                    Image generation:
+                    - You do not generate images directly and you do not call any image tool.
+                    - When the user asks for an image, include markdown notation in your message:
+                      \`![<alt text>](?image-prompt=<prompt>)\`
+                    - Keep \`<alt text>\` short and descriptive.
+                    - Keep \`<prompt>\` detailed so the generated image matches the request.
+                    - You can include normal explanatory text before and after the notation.
+                    ${block(extraInstructions)}
+                `));
         }
     }
     /**
@@ -18967,6 +19323,221 @@
      * Note: [💞] Ignore a discrepancy between file name and entity name
      */
 
+    /**
+     * Tool name used by the USE USER LOCATION commitment.
+     *
+     * @private internal USE USER LOCATION constant
+     */
+    const GET_USER_LOCATION_TOOL_NAME = 'get_user_location';
+    /**
+     * Returns a finite number when valid.
+     *
+     * @private utility of USE USER LOCATION commitment
+     */
+    function normalizeFiniteNumber(value) {
+        if (typeof value !== 'number') {
+            return undefined;
+        }
+        return Number.isFinite(value) ? value : undefined;
+    }
+    /**
+     * Returns a finite number or null when explicitly null.
+     *
+     * @private utility of USE USER LOCATION commitment
+     */
+    function normalizeNullableFiniteNumber(value) {
+        if (value === null) {
+            return null;
+        }
+        return normalizeFiniteNumber(value);
+    }
+    /**
+     * Normalizes raw runtime location payload into a safe location object.
+     *
+     * @private utility of USE USER LOCATION commitment
+     */
+    function normalizeUserLocation(location) {
+        return {
+            permission: location.permission,
+            latitude: normalizeFiniteNumber(location.latitude),
+            longitude: normalizeFiniteNumber(location.longitude),
+            accuracyMeters: normalizeFiniteNumber(location.accuracyMeters),
+            altitudeMeters: normalizeNullableFiniteNumber(location.altitudeMeters),
+            headingDegrees: normalizeNullableFiniteNumber(location.headingDegrees),
+            speedMetersPerSecond: normalizeNullableFiniteNumber(location.speedMetersPerSecond),
+            timestamp: typeof location.timestamp === 'string' ? location.timestamp : undefined,
+        };
+    }
+    /**
+     * Resolves the user location payload from hidden tool runtime context.
+     *
+     * @private utility of USE USER LOCATION commitment
+     */
+    function resolveUserLocationFromRuntimeContext(args) {
+        const runtimeContext = readToolRuntimeContextFromToolArgs(args);
+        const location = runtimeContext === null || runtimeContext === void 0 ? void 0 : runtimeContext.userLocation;
+        if (!location || typeof location !== 'object') {
+            return null;
+        }
+        return normalizeUserLocation(location);
+    }
+    /**
+     * Creates a standard "unavailable location" tool result.
+     *
+     * @private utility of USE USER LOCATION commitment
+     */
+    function createUnavailableLocationResult() {
+        return {
+            status: 'unavailable',
+            message: 'User location is not available in this runtime context. Ask the user to allow location sharing in browser, or ask for their city manually.',
+        };
+    }
+    /**
+     * Creates a standard "permission denied" tool result.
+     *
+     * @private utility of USE USER LOCATION commitment
+     */
+    function createPermissionDeniedResult() {
+        return {
+            status: 'permission-denied',
+            message: 'Location access is denied by the user/browser. Ask the user to enable location access or provide their location manually.',
+        };
+    }
+    /**
+     * USE USER LOCATION commitment definition.
+     *
+     * The `USE USER LOCATION` commitment enables an agent to retrieve user location from runtime context.
+     *
+     * @private [🪔] Maybe export the commitments through some package
+     */
+    class UseUserLocationCommitmentDefinition extends BaseCommitmentDefinition {
+        constructor() {
+            super('USE USER LOCATION', ['USER LOCATION']);
+        }
+        get requiresContent() {
+            return false;
+        }
+        /**
+         * Short one-line description of USE USER LOCATION.
+         */
+        get description() {
+            return 'Enable the agent to determine the user location when browser permission is granted.';
+        }
+        /**
+         * Icon for this commitment.
+         */
+        get icon() {
+            return '📍';
+        }
+        /**
+         * Markdown documentation for USE USER LOCATION commitment.
+         */
+        get documentation() {
+            return spaceTrim$1.spaceTrim(`
+            # USE USER LOCATION
+
+            Enables the agent to retrieve the user's location from runtime context.
+
+            ## Key aspects
+
+            - The location is requested by the browser runtime (with user permission).
+            - Use the tool \`get_user_location\` when an answer depends on user's location.
+            - If location is unavailable or denied, ask the user to enable location sharing or provide location manually.
+            - The content following \`USE USER LOCATION\` can define additional location usage instructions.
+
+            ## Examples
+
+            \`\`\`book
+            Local Assistant
+
+            PERSONA You help with local recommendations.
+            USE USER LOCATION
+            \`\`\`
+
+            \`\`\`book
+            Travel Assistant
+
+            PERSONA You help users with nearby transport and weather.
+            USE USER LOCATION Use location only when strictly needed.
+            \`\`\`
+        `);
+        }
+        applyToAgentModelRequirements(requirements, content) {
+            const extraInstructions = formatOptionalInstructionBlock('User location instructions', content);
+            const existingTools = requirements.tools || [];
+            const tools = existingTools.some((tool) => tool.name === GET_USER_LOCATION_TOOL_NAME)
+                ? existingTools
+                : [
+                    ...existingTools,
+                    {
+                        name: GET_USER_LOCATION_TOOL_NAME,
+                        description: spaceTrim$1.spaceTrim(`
+                          Retrieves user location shared by browser runtime (if permission is granted).
+                          Returns JSON status with coordinates and metadata when available.
+                      `),
+                        parameters: {
+                            type: 'object',
+                            properties: {},
+                            required: [],
+                        },
+                    },
+                ];
+            return this.appendToSystemMessage({
+                ...requirements,
+                tools,
+                _metadata: {
+                    ...requirements._metadata,
+                    useUserLocation: content || true,
+                },
+            }, spaceTrim$1.spaceTrim((block) => `
+                    User location:
+                    - Use "${GET_USER_LOCATION_TOOL_NAME}" only when location is needed for a better answer.
+                    - If the tool returns "unavailable" or "permission-denied", ask user to share location or provide city manually.
+                    - Do not invent coordinates or local facts when location is unavailable.
+                    ${block(extraInstructions)}
+                `));
+        }
+        /**
+         * Gets human-readable titles for tool functions provided by this commitment.
+         */
+        getToolTitles() {
+            return {
+                [GET_USER_LOCATION_TOOL_NAME]: 'Get user location',
+            };
+        }
+        /**
+         * Gets the `get_user_location` tool function implementation.
+         */
+        getToolFunctions() {
+            return {
+                async [GET_USER_LOCATION_TOOL_NAME](args) {
+                    const location = resolveUserLocationFromRuntimeContext(args);
+                    if (!location) {
+                        return JSON.stringify(createUnavailableLocationResult());
+                    }
+                    if (location.permission === 'denied') {
+                        return JSON.stringify(createPermissionDeniedResult());
+                    }
+                    if (location.latitude === undefined || location.longitude === undefined) {
+                        return JSON.stringify(createUnavailableLocationResult());
+                    }
+                    const result = {
+                        status: 'ok',
+                        location: {
+                            ...location,
+                            permission: location.permission || 'granted',
+                        },
+                        message: 'User location is available.',
+                    };
+                    return JSON.stringify(result);
+                },
+            };
+        }
+    }
+    /**
+     * Note: [💞] Ignore a discrepancy between file name and entity name
+     */
+
     /**
      * Placeholder commitment definition for commitments that are not yet implemented
      *
@@ -19034,6 +19605,7 @@
         }
     }
 
+    // Import all commitment definition classes
     /**
      * Registry of all available commitment definitions
      * This array contains instances of all commitment definitions
@@ -19072,7 +19644,9 @@
         new MetaColorCommitmentDefinition(),
         new MetaFontCommitmentDefinition(),
         new MetaLinkCommitmentDefinition(),
+        new MetaDisclaimerCommitmentDefinition(),
         new MetaCommitmentDefinition(),
+        new MetaVoiceCommitmentDefinition(),
         new NoteCommitmentDefinition('NOTE'),
         new NoteCommitmentDefinition('NOTES'),
         new NoteCommitmentDefinition('COMMENT'),
@@ -19083,6 +19657,7 @@
         new InitialMessageCommitmentDefinition(),
         new UserMessageCommitmentDefinition(),
         new AgentMessageCommitmentDefinition(),
+        new MessageSuffixCommitmentDefinition(),
         new MessageCommitmentDefinition('MESSAGE'),
         new MessageCommitmentDefinition('MESSAGES'),
         new ScenarioCommitmentDefinition('SCENARIO'),
@@ -19098,13 +19673,9 @@
         new UseBrowserCommitmentDefinition(),
         new UseSearchEngineCommitmentDefinition(),
         new UseTimeCommitmentDefinition(),
+        new UseUserLocationCommitmentDefinition(),
         new UseEmailCommitmentDefinition(),
         new UseImageGeneratorCommitmentDefinition('USE IMAGE GENERATOR'),
-        new UseImageGeneratorCommitmentDefinition('USE IMAGE GENERATION' /* <- TODO: Remove any */),
-        new UseImageGeneratorCommitmentDefinition('IMAGE GENERATOR' /* <- TODO: Remove any */),
-        new UseImageGeneratorCommitmentDefinition('IMAGE GENERATION' /* <- TODO: Remove any */),
-        new UseImageGeneratorCommitmentDefinition('USE IMAGE' /* <- TODO: Remove any */),
-        // <- Note: [⛹️] How to deal with commitment aliases with defined functions
         new UseMcpCommitmentDefinition(),
         new UseCommitmentDefinition(),
         // Not yet implemented commitments (using placeholder)
@@ -20975,27 +21546,6 @@
         return `fallback:${toolCall.name}:${argsKey}`;
     }
 
-    /*! *****************************************************************************
-    Copyright (c) Microsoft Corporation.
-
-    Permission to use, copy, modify, and/or distribute this software for any
-    purpose with or without fee is hereby granted.
-
-    THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
-    REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
-    AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
-    INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
-    LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
-    OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
-    PERFORMANCE OF THIS SOFTWARE.
-    ***************************************************************************** */
-
-    function __classPrivateFieldGet(receiver, state, kind, f) {
-        if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
-        if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
-        return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
-    }
-
     /**
      * Computes SHA-256 hash of the agent source
      *
@@ -21310,6 +21860,7 @@
         const capabilities = [];
         const samples = [];
         const knowledgeSources = [];
+        const knownKnowledgeSourceUrls = new Set();
         let pendingUserMessage = null;
         for (const commitment of parseResult.commitments) {
             if (commitment.type === 'INITIAL MESSAGE') {
@@ -21359,6 +21910,14 @@
                 });
                 continue;
             }
+            if (commitment.type === 'USE USER LOCATION') {
+                capabilities.push({
+                    type: 'user-location',
+                    label: 'User location',
+                    iconName: 'MapPin',
+                });
+                continue;
+            }
             if (commitment.type === 'USE EMAIL' /* || commitment.type === 'EMAIL' || commitment.type === 'MAIL' */) {
                 capabilities.push({
                     type: 'email',
@@ -21437,21 +21996,34 @@
                 continue;
             }
             if (commitment.type === 'KNOWLEDGE') {
-                const content = spaceTrim__default["default"](commitment.content).split(/\r?\n/)[0] || '';
+                const content = spaceTrim__default["default"](commitment.content);
+                const extractedUrls = extractUrlsFromText(content);
                 let label = content;
                 let iconName = 'Book';
-                // Check if this is a URL (for knowledge sources resolution)
-                if (content.startsWith('http://') || content.startsWith('https://')) {
+                // Store URL references for citation resolution.
+                for (const extractedUrl of extractedUrls) {
+                    if (knownKnowledgeSourceUrls.has(extractedUrl)) {
+                        continue;
+                    }
+                    try {
+                        const urlObject = new URL(extractedUrl);
+                        const pathSegment = decodeURIComponent(urlObject.pathname.split('/').pop() || '');
+                        const filename = pathSegment || urlObject.hostname;
+                        knowledgeSources.push({
+                            url: extractedUrl,
+                            filename,
+                        });
+                        knownKnowledgeSourceUrls.add(extractedUrl);
+                    }
+                    catch (error) {
+                        // Invalid URL, ignore in profile metadata
+                    }
+                }
+                if (extractedUrls.length > 0) {
                     try {
-                        const url = new URL(content);
-                        const filename = url.pathname.split('/').pop() || '';
-                        // Store the URL and filename for citation resolution
-                        if (filename) {
-                            knowledgeSources.push({
-                                url: content,
-                                filename,
-                            });
-                        }
+                        const primaryUrl = extractedUrls[0];
+                        const url = new URL(primaryUrl);
+                        const filename = decodeURIComponent(url.pathname.split('/').pop() || '');
                         // Determine display label and icon
                         if (url.pathname.endsWith('.pdf')) {
                             label = filename || 'Document.pdf';
@@ -21460,6 +22032,9 @@
                         else {
                             label = url.hostname.replace(/^www\./, '');
                         }
+                        if (extractedUrls.length > 1) {
+                            label = `${label} (+${extractedUrls.length - 1})`;
+                        }
                     }
                     catch (e) {
                         // Invalid URL, treat as text
@@ -21493,6 +22068,14 @@
                 meta.description = spaceTrim__default["default"](commitment.content);
                 continue;
             }
+            if (commitment.type === 'META DISCLAIMER') {
+                meta.disclaimer = commitment.content;
+                continue;
+            }
+            if (commitment.type === 'MESSAGE SUFFIX') {
+                meta.messageSuffix = commitment.content;
+                continue;
+            }
             if (commitment.type === 'META COLOR') {
                 meta.color = normalizeSeparator(commitment.content);
                 continue;
@@ -21501,6 +22084,10 @@
                 meta.font = normalizeSeparator(commitment.content);
                 continue;
             }
+            if (commitment.type === 'META VOICE') {
+                meta.voice = spaceTrim__default["default"](commitment.content);
+                continue;
+            }
             if (commitment.type !== 'META') {
                 continue;
             }
@@ -23281,17 +23868,17 @@
         /**
          * Calls OpenAI compatible API to use a chat model with streaming.
          */
-        async callChatModelStream(prompt, onProgress) {
+        async callChatModelStream(prompt, onProgress, options) {
             // Deep clone prompt and modelRequirements to avoid mutation across calls
             const clonedPrompt = clonePromptPreservingFiles(prompt);
             // Use local Set for retried parameters to ensure independence and thread safety
             const retriedUnsupportedParameters = new Set();
-            return this.callChatModelWithRetry(clonedPrompt, clonedPrompt.modelRequirements, [], retriedUnsupportedParameters, onProgress);
+            return this.callChatModelWithRetry(clonedPrompt, clonedPrompt.modelRequirements, [], retriedUnsupportedParameters, onProgress, options);
         }
         /**
          * Internal method that handles parameter retry for chat model calls
          */
-        async callChatModelWithRetry(prompt, currentModelRequirements, attemptStack = [], retriedUnsupportedParameters = new Set(), onProgress) {
+        async callChatModelWithRetry(prompt, currentModelRequirements, attemptStack = [], retriedUnsupportedParameters = new Set(), onProgress, options) {
             var _a;
             if (this.options.isVerbose) {
                 console.info(`💬 ${this.title} callChatModel call`, { prompt, currentModelRequirements });
@@ -23583,7 +24170,7 @@
                     });
                     // Remove the unsupported parameter and retry
                     const modifiedModelRequirements = removeUnsupportedModelRequirement(currentModelRequirements, unsupportedParameter);
-                    return this.callChatModelWithRetry(prompt, modifiedModelRequirements, attemptStack, retriedUnsupportedParameters, onProgress);
+                    return this.callChatModelWithRetry(prompt, modifiedModelRequirements, attemptStack, retriedUnsupportedParameters, onProgress, options);
                 }
             }
             throw new PipelineExecutionError(`Tool calling loop did not return a result from ${this.title}`);
@@ -25019,7 +25606,7 @@
         /**
          * Calls OpenAI AgentKit with a chat prompt (streaming).
          */
-        async callChatModelStream(prompt, onProgress) {
+        async callChatModelStream(prompt, onProgress, options) {
             const { content, parameters, modelRequirements } = prompt;
             if (modelRequirements.modelVariant !== 'CHAT') {
                 throw new PipelineExecutionError('Use callChatModel only for CHAT variant');
@@ -25046,6 +25633,7 @@
                 rawPromptContent,
                 onProgress,
                 responseFormatOutputType,
+                signal: options === null || options === void 0 ? void 0 : options.signal,
             });
         }
         /**
@@ -25244,6 +25832,7 @@
             const streamResult = await agents.run(agentForRun, inputItems, {
                 stream: true,
                 context: { parameters: prompt.parameters },
+                signal: options.signal,
             });
             for await (const event of streamResult) {
                 if (event.type === 'raw_model_stream_event' && ((_b = event.data) === null || _b === void 0 ? void 0 : _b.type) === 'output_text_delta') {
@@ -25484,7 +26073,7 @@
         /**
          * Calls OpenAI API to use a chat model with streaming.
          */
-        async callChatModelStream(prompt, onProgress) {
+        async callChatModelStream(prompt, onProgress, options) {
             var _a, _b, _c, _d, _e, _f;
             if (this.options.isVerbose) {
                 console.info('💬 OpenAI callChatModel call', { prompt });
@@ -26080,6 +26669,24 @@
             ],
         });
     }
+    /**
+     * Merges the agent's predefined knowledge sources with user-provided attachment URLs.
+     *
+     * @private internal helper for `AgentLlmExecutionTools`
+     */
+    function mergeKnowledgeSourcesWithAttachments(baseSources, attachmentUrls) {
+        const combined = [];
+        if (baseSources && baseSources.length > 0) {
+            combined.push(...baseSources.filter((value) => typeof value === 'string' && value.trim() !== ''));
+        }
+        for (const url of attachmentUrls) {
+            const trimmed = String(url !== null && url !== void 0 ? url : '').trim();
+            if (trimmed !== '') {
+                combined.push(trimmed);
+            }
+        }
+        return Array.from(new Set(combined));
+    }
     /**
      * Execution Tools for calling LLM models with a predefined agent "soul"
      * This wraps underlying LLM execution tools and applies agent-specific system prompts and requirements
@@ -26223,8 +26830,8 @@
         /**
          * Calls the chat model with agent-specific system prompt and requirements with streaming
          */
-        async callChatModelStream(prompt, onProgress) {
-            var _a, _b;
+        async callChatModelStream(prompt, onProgress, options) {
+            var _a;
             // Ensure we're working with a chat prompt
             if (prompt.modelRequirements.modelVariant !== 'CHAT') {
                 throw new Error('AgentLlmExecutionTools only supports chat prompts');
@@ -26232,6 +26839,14 @@
             const modelRequirements = await this.getModelRequirements();
             const { _metadata, promptSuffix, ...sanitizedRequirements } = modelRequirements;
             const chatPrompt = prompt;
+            const attachmentUrls = Array.isArray(chatPrompt.attachments) && chatPrompt.attachments.length > 0
+                ? chatPrompt.attachments
+                    .map((attachment) => (typeof (attachment === null || attachment === void 0 ? void 0 : attachment.url) === 'string' ? attachment.url.trim() : ''))
+                    .filter((url) => url !== '')
+                : [];
+            const knowledgeSourcesForAgentList = mergeKnowledgeSourcesWithAttachments(sanitizedRequirements.knowledgeSources, attachmentUrls);
+            const knowledgeSourcesForAgent = knowledgeSourcesForAgentList.length > 0 ? knowledgeSourcesForAgentList : undefined;
+            const hasAttachmentSources = attachmentUrls.length > 0;
             let underlyingLlmResult;
             const chatPromptContentWithSuffix = promptSuffix
                 ? `${chatPrompt.content}\n\n${promptSuffix}`
@@ -26247,9 +26862,7 @@
                         ? [...sanitizedRequirements.tools]
                         : chatPrompt.modelRequirements.tools,
                     // Spread knowledgeSources to convert readonly array to mutable
-                    knowledgeSources: sanitizedRequirements.knowledgeSources
-                        ? [...sanitizedRequirements.knowledgeSources]
-                        : undefined,
+                    knowledgeSources: knowledgeSourcesForAgent,
                     // Prepend agent system message to existing system message
                     systemMessage: sanitizedRequirements.systemMessage +
                         (chatPrompt.modelRequirements.systemMessage
@@ -26259,27 +26872,34 @@
             };
             console.log('!!!! promptWithAgentModelRequirements:', promptWithAgentModelRequirements);
             if (OpenAiAgentKitExecutionTools.isOpenAiAgentKitExecutionTools(this.options.llmTools)) {
-                const requirementsHash = cryptoJs.SHA256(JSON.stringify(sanitizedRequirements)).toString();
-                const vectorStoreHash = cryptoJs.SHA256(JSON.stringify((_a = sanitizedRequirements.knowledgeSources) !== null && _a !== void 0 ? _a : [])).toString();
-                const cachedVectorStore = AgentLlmExecutionTools.vectorStoreCache.get(this.title);
-                const cachedAgentKit = AgentLlmExecutionTools.agentKitAgentCache.get(this.title);
-                let preparedAgentKit = this.options.assistantPreparationMode === 'external'
+                const shouldUseCache = !hasAttachmentSources;
+                let preparedAgentKit = shouldUseCache && this.options.assistantPreparationMode === 'external'
                     ? this.options.llmTools.getPreparedAgentKitAgent()
                     : null;
-                const vectorStoreId = (preparedAgentKit === null || preparedAgentKit === void 0 ? void 0 : preparedAgentKit.vectorStoreId) ||
-                    (cachedVectorStore && cachedVectorStore.requirementsHash === vectorStoreHash
-                        ? cachedVectorStore.vectorStoreId
-                        : undefined);
-                if (!preparedAgentKit && cachedAgentKit && cachedAgentKit.requirementsHash === requirementsHash) {
-                    if (this.options.isVerbose) {
-                        console.info('[🤰]', 'Using cached OpenAI AgentKit agent', {
-                            agent: this.title,
-                        });
+                let vectorStoreId;
+                let vectorStoreHash;
+                let requirementsHash;
+                if (shouldUseCache) {
+                    requirementsHash = cryptoJs.SHA256(JSON.stringify(sanitizedRequirements)).toString();
+                    vectorStoreHash = cryptoJs.SHA256(JSON.stringify((_a = sanitizedRequirements.knowledgeSources) !== null && _a !== void 0 ? _a : [])).toString();
+                    const cachedVectorStore = AgentLlmExecutionTools.vectorStoreCache.get(this.title);
+                    const cachedAgentKit = AgentLlmExecutionTools.agentKitAgentCache.get(this.title);
+                    vectorStoreId =
+                        (preparedAgentKit === null || preparedAgentKit === void 0 ? void 0 : preparedAgentKit.vectorStoreId) ||
+                            (cachedVectorStore && cachedVectorStore.requirementsHash === vectorStoreHash
+                                ? cachedVectorStore.vectorStoreId
+                                : undefined);
+                    if (!preparedAgentKit && cachedAgentKit && cachedAgentKit.requirementsHash === requirementsHash) {
+                        if (this.options.isVerbose) {
+                            console.info('[🤰]', 'Using cached OpenAI AgentKit agent', {
+                                agent: this.title,
+                            });
+                        }
+                        preparedAgentKit = {
+                            agent: cachedAgentKit.agent,
+                            vectorStoreId: cachedAgentKit.vectorStoreId,
+                        };
                     }
-                    preparedAgentKit = {
-                        agent: cachedAgentKit.agent,
-                        vectorStoreId: cachedAgentKit.vectorStoreId,
-                    };
                 }
                 if (!preparedAgentKit) {
                     if (this.options.isVerbose) {
@@ -26287,7 +26907,7 @@
                             agent: this.title,
                         });
                     }
-                    if (!vectorStoreId && ((_b = sanitizedRequirements.knowledgeSources) === null || _b === void 0 ? void 0 : _b.length)) {
+                    if (!vectorStoreId && (knowledgeSourcesForAgent === null || knowledgeSourcesForAgent === void 0 ? void 0 : knowledgeSourcesForAgent.length)) {
                         emitAssistantPreparationProgress({
                             onProgress,
                             prompt,
@@ -26304,28 +26924,31 @@
                     preparedAgentKit = await this.options.llmTools.prepareAgentKitAgent({
                         name: this.title,
                         instructions: sanitizedRequirements.systemMessage || '',
-                        knowledgeSources: sanitizedRequirements.knowledgeSources,
+                        knowledgeSources: knowledgeSourcesForAgent,
                         tools: sanitizedRequirements.tools ? [...sanitizedRequirements.tools] : undefined,
-                        vectorStoreId,
+                        vectorStoreId: shouldUseCache ? vectorStoreId : undefined,
                     });
                 }
-                if (preparedAgentKit.vectorStoreId) {
+                if (shouldUseCache && vectorStoreHash && preparedAgentKit.vectorStoreId) {
                     AgentLlmExecutionTools.vectorStoreCache.set(this.title, {
                         vectorStoreId: preparedAgentKit.vectorStoreId,
                         requirementsHash: vectorStoreHash,
                     });
                 }
-                AgentLlmExecutionTools.agentKitAgentCache.set(this.title, {
-                    agent: preparedAgentKit.agent,
-                    requirementsHash,
-                    vectorStoreId: preparedAgentKit.vectorStoreId,
-                });
+                if (shouldUseCache && requirementsHash) {
+                    AgentLlmExecutionTools.agentKitAgentCache.set(this.title, {
+                        agent: preparedAgentKit.agent,
+                        requirementsHash,
+                        vectorStoreId: preparedAgentKit.vectorStoreId,
+                    });
+                }
                 const responseFormatOutputType = mapResponseFormatToAgentOutputType(promptWithAgentModelRequirements.modelRequirements.responseFormat);
                 underlyingLlmResult = await this.options.llmTools.callChatModelStreamWithPreparedAgent({
                     openAiAgentKitAgent: preparedAgentKit.agent,
                     prompt: promptWithAgentModelRequirements,
                     onProgress,
                     responseFormatOutputType,
+                    signal: options === null || options === void 0 ? void 0 : options.signal,
                 });
             }
             else if (OpenAiAssistantExecutionTools.isOpenAiAssistantExecutionTools(this.options.llmTools)) {
@@ -26423,14 +27046,14 @@
                     },
                 };
                 console.log('!!!! promptWithAgentModelRequirementsForOpenAiAssistantExecutionTools:', promptWithAgentModelRequirementsForOpenAiAssistantExecutionTools);
-                underlyingLlmResult = await assistant.callChatModelStream(promptWithAgentModelRequirementsForOpenAiAssistantExecutionTools, onProgress);
+                underlyingLlmResult = await assistant.callChatModelStream(promptWithAgentModelRequirementsForOpenAiAssistantExecutionTools, onProgress, options);
             }
             else {
                 if (this.options.isVerbose) {
                     console.log(`2️⃣ Creating Assistant ${this.title} on generic LLM execution tools...`);
                 }
                 if (this.options.llmTools.callChatModelStream) {
-                    underlyingLlmResult = await this.options.llmTools.callChatModelStream(promptWithAgentModelRequirements, onProgress);
+                    underlyingLlmResult = await this.options.llmTools.callChatModelStream(promptWithAgentModelRequirements, onProgress, options);
                 }
                 else if (this.options.llmTools.callChatModel) {
                     underlyingLlmResult = await this.options.llmTools.callChatModel(promptWithAgentModelRequirements);
@@ -26476,9 +27099,179 @@
      * TODO: [🧠] Adding parameter substitution support (here or should be responsibility of the underlying LLM Tools)
      */
 
-    var _Agent_instances, _Agent_selfLearnNonce, _Agent_selfLearnSamples, _Agent_selfLearnTeacher;
+    /**
+     * Extracts the teacher-focused instructions from the latest `OPEN` commitment in the book.
+     *
+     * The `OPEN` commitment may include extra text that should guide the teacher agent when
+     * self-learning. We keep the last non-empty `OPEN` value so later overrides win.
+     *
+     * @param agentSource - The raw agent book source
+     * @returns The trimmed instructions or `null` when no instructive `OPEN` commitment exists.
+     * @private Internal helper shared between self-learning and related features.
+     */
+    function extractOpenTeacherInstructions(agentSource) {
+        const { commitments } = parseAgentSourceWithCommitments(agentSource);
+        for (let i = commitments.length - 1; i >= 0; i -= 1) {
+            const commitment = commitments[i];
+            if (commitment.type !== 'OPEN') {
+                continue;
+            }
+            const trimmed = spaceTrim$1.spaceTrim(commitment.content);
+            return trimmed || null;
+        }
+        return null;
+    }
+
+    /**
+     * Coordinates the Agent self-learning workflow that was extracted from the main class.
+     *
+     * @private helper for Agent
+     */
+    class SelfLearningManager {
+        constructor(options) {
+            this.options = options;
+            this.teacherAgent = options.teacherAgent;
+        }
+        /**
+         * Runs nonce, sampling, and teacher steps for every interaction that should learn.
+         *
+         * @param prompt Received prompt for the interaction
+         * @param result Response produced by the agent
+         * @returns Teacher summary or null when no teacher is configured
+         * @private helper of Agent
+         */
+        async runSelfLearning(prompt, result) {
+            if (just(false)) {
+                await this.appendNonce();
+            }
+            this.appendSample(prompt, result);
+            if (this.teacherAgent === null) {
+                return null;
+            }
+            try {
+                return await this.callTeacher(prompt, result);
+            }
+            catch (error) {
+                console.error(colors__default["default"].bgCyan('[Self-learning]') + colors__default["default"].red(' Failed to learn from teacher agent'));
+                console.error(error);
+                return buildTeacherSummary('', true);
+            }
+        }
+        /**
+         * Appends the nonce section to the agent source with slight delay to avoid thundering herd lookups.
+         *
+         * @private helper of Agent
+         */
+        async appendNonce() {
+            await waitasecond.forTime(Math.random() * 5000);
+            console.info(colors__default["default"].bgCyan('[Self-learning]') + colors__default["default"].cyan(' Nonce'));
+            const nonce = `NONCE ${await linguisticHash(Math.random().toString())}`;
+            this.appendToAgentSource('\n\n---\n\n' + nonce);
+        }
+        /**
+         * Appends the recent user/agent exchange as a new sample.
+         *
+         * @private helper of Agent
+         */
+        appendSample(prompt, result) {
+            console.info(colors__default["default"].bgCyan('[Self-learning]') + colors__default["default"].cyan(' Sampling'));
+            const learningExample = spaceTrim__default["default"]((block) => `
+
+                USER MESSAGE
+                ${block(prompt.content)}
+
+                AGENT MESSAGE
+                ${block(result.content)}
+
+            `);
+            this.appendToAgentSource('\n\n---\n\n' + learningExample);
+        }
+        /**
+         * Calls the teacher agent, appends its commitments, and summarizes the results.
+         *
+         * @private helper of Agent
+         */
+        async callTeacher(prompt, result) {
+            console.info(colors__default["default"].bgCyan('[Self-learning]') + colors__default["default"].cyan(' Teacher'));
+            const teacherInstructions = extractOpenTeacherInstructions(this.options.getAgentSource());
+            const teacherInstructionsSection = teacherInstructions
+                ? spaceTrim__default["default"]((block) => `
+                      **Teacher instructions:**
+                      ${block(teacherInstructions)}
+                  `)
+                : '';
+            const teacherPromptContent = spaceTrim__default["default"]((block) => `
+
+                You are a teacher agent helping another agent to learn from its interactions.
+
+                Here is your current client which you are teaching:
+
+                \`\`\`book
+                ${block(this.options.getAgentSource())}
+                \`\`\`
+
+                **And here is the latest interaction:**
+
+                **User:**
+                ${block(prompt.content)}
+
+                **Agent:**
+                ${block(result.content)}
+
+                ${teacherInstructionsSection ? `\n${teacherInstructionsSection}` : ''}
+
+                **Rules:**
+
+                - Decide what the agent should learn from this interaction.
+                - Append new commitments at the end of the agent source.
+                - Do not modify the current agent source, just return new commitments (KNOWLEDGE, RULE, etc.).
+                - If there is nothing new to learn, return empty book code block
+                - Wrap the commitments in a book code block.
+                - Do not explain anything, just return the commitments wrapped in a book code block.
+                - Write the learned commitments in the same style and language as in the original agent source.
+
+
+                This is how book code block looks like:
+
+                \`\`\`book
+                KNOWLEDGE The sky is blue.
+                RULE Always be polite.
+                \`\`\`
+            `);
+            const teacherResult = await this.teacherAgent.callChatModel({
+                title: 'Self-learning',
+                modelRequirements: {
+                    modelVariant: 'CHAT',
+                },
+                content: teacherPromptContent,
+                parameters: {},
+            });
+            console.log('!!!! teacherResult', teacherResult);
+            const teacherCommitments = unwrapResult(teacherResult.content);
+            if (teacherCommitments === '') {
+                console.info(colors__default["default"].bgCyan('[Self-learning]') +
+                    colors__default["default"].cyan(' Teacher agent did not provide new commitments to learn'));
+                return buildTeacherSummary('', true);
+            }
+            this.appendToAgentSource('\n\n' + teacherCommitments);
+            return buildTeacherSummary(teacherCommitments, true);
+        }
+        /**
+         * Appends a new fragment to the agent source and triggers normalization.
+         *
+         * @param section Fragment that should be appended
+         * @private helper of Agent
+         */
+        appendToAgentSource(section) {
+            const currentSource = this.options.getAgentSource();
+            const newSource = padBook(validateBook(spaceTrim__default["default"](currentSource) + section));
+            this.options.updateAgentSource(newSource);
+        }
+    }
     /**
      * Creates an empty commitment breakdown for self-learning summaries.
+     *
+     * @private function of Agent
      */
     function createEmptySelfLearningCommitmentCounts() {
         return {
@@ -26491,6 +27284,9 @@
     }
     /**
      * Normalizes teacher commitments into trimmed, display-ready lines.
+     *
+     * @param commitments Raw teacher output
+     * @private function of Agent
      */
     function getTeacherCommitmentLines(commitments) {
         return commitments
@@ -26500,6 +27296,9 @@
     }
     /**
      * Summarizes teacher commitment lines into user-friendly counts for self-learning.
+     *
+     * @param lines Parsed teacher commitment lines
+     * @private function of Agent
      */
     function summarizeTeacherCommitmentLines(lines) {
         var _a, _b;
@@ -26527,6 +27326,11 @@
     }
     /**
      * Builds the teacher summary payload for the self-learning tool call.
+     *
+     * @param commitments Raw teacher commitments
+     * @param used Whether the teacher was invoked
+     * @returns Summary of learned commitments
+     * @private function of Agent
      */
     function buildTeacherSummary(commitments, used) {
         const commitmentLines = getTeacherCommitmentLines(commitments);
@@ -26536,6 +27340,34 @@
             commitments: commitmentLines.length > 0 ? commitmentLines : undefined,
         };
     }
+
+    /**
+     * Parses boolean prompt parameters, defaulting when the value is missing or invalid.
+     *
+     * @private
+     */
+    function parseBooleanPromptParameter(value, fallback) {
+        if (value === undefined) {
+            return fallback;
+        }
+        const normalized = value.trim().toLowerCase();
+        if (normalized === 'true') {
+            return true;
+        }
+        if (normalized === 'false') {
+            return false;
+        }
+        try {
+            const parsed = JSON.parse(value);
+            if (typeof parsed === 'boolean') {
+                return parsed;
+            }
+        }
+        catch (_a) {
+            // If JSON parsing fails, fall back to the default.
+        }
+        return fallback;
+    }
     /**
      * Represents one AI Agent
      *
@@ -26578,7 +27410,6 @@
                 assistantPreparationMode: options.assistantPreparationMode,
                 agentSource: agentSource.value, // <- TODO: [🐱‍🚀] Allow to pass BehaviorSubject<string_book> OR refresh llmExecutionTools.callChat on agentSource change
             });
-            _Agent_instances.add(this);
             this._agentName = undefined;
             /**
              * Description of the agent
@@ -26617,8 +27448,12 @@
             this.toolTitles = {};
             // TODO: [🐱‍🚀] Add `Agent` simple "mocked" learning by appending to agent source
             // TODO: [🐱‍🚀] Add `Agent` learning by promptbookAgent
-            this.teacherAgent = options.teacherAgent;
             this.agentSource = agentSource;
+            this.selfLearningManager = new SelfLearningManager({
+                teacherAgent: options.teacherAgent,
+                getAgentSource: () => this.agentSource.value,
+                updateAgentSource: (source) => this.agentSource.next(source),
+            });
             this.agentSource.subscribe((source) => {
                 this.updateAgentSource(source);
                 const { agentName, personaDescription, initialMessage, links, meta, capabilities, samples, knowledgeSources, } = parseAgentSource(source);
@@ -26641,7 +27476,8 @@
          *
          * Note: This method also implements the learning mechanism
          */
-        async callChatModelStream(prompt, onProgress) {
+        async callChatModelStream(prompt, onProgress, options) {
+            var _a;
             // [1] Check if the user is asking the same thing as in the samples
             const modelRequirements = await this.getModelRequirements();
             if (modelRequirements.samples) {
@@ -26685,13 +27521,17 @@
                     return result;
                 }
             }
-            const result = await super.callChatModelStream(prompt, onProgress);
+            const result = await super.callChatModelStream(prompt, onProgress, options);
             if (result.rawResponse && 'sample' in result.rawResponse) {
                 return result;
             }
             if (modelRequirements.isClosed) {
                 return result;
             }
+            const shouldSelfLearn = parseBooleanPromptParameter((_a = prompt.parameters) === null || _a === void 0 ? void 0 : _a[PROMPT_PARAMETER_SELF_LEARNING_ENABLED], true);
+            if (!shouldSelfLearn) {
+                return result;
+            }
             // Note: [0] Notify start of self-learning
             const selfLearningToolCall = {
                 name: 'self-learning',
@@ -26703,24 +27543,7 @@
                 toolCalls: [...(result.toolCalls || []), selfLearningToolCall],
             };
             onProgress(resultWithLearning);
-            // Note: [1] Asynchronously add nonce
-            if (just(false)) {
-                await __classPrivateFieldGet(this, _Agent_instances, "m", _Agent_selfLearnNonce).call(this);
-            }
-            // Note: [2] Do the append of the samples
-            await __classPrivateFieldGet(this, _Agent_instances, "m", _Agent_selfLearnSamples).call(this, prompt, result);
-            // Note: [3] Asynchronously call the teacher agent and invoke the silver link. When the teacher fails, keep just the samples
-            let teacherSummary = null;
-            try {
-                teacherSummary = await __classPrivateFieldGet(this, _Agent_instances, "m", _Agent_selfLearnTeacher).call(this, prompt, result);
-            }
-            catch (error) {
-                // !!!!! if (this.options.isVerbose) {
-                console.error(colors__default["default"].bgCyan('[Self-learning]') + colors__default["default"].red(' Failed to learn from teacher agent'));
-                console.error(error);
-                // }
-                teacherSummary = this.teacherAgent ? buildTeacherSummary('', true) : null;
-            }
+            const teacherSummary = await this.selfLearningManager.runSelfLearning(prompt, result);
             // Note: [4] Notify end of self-learning
             const completedAt = new Date().toISOString();
             const selfLearningResult = {
@@ -26742,110 +27565,6 @@
             return finalResult;
         }
     }
-    _Agent_instances = new WeakSet(), _Agent_selfLearnNonce = 
-    /**
-     * Self-learning Step 0: Asynchronously with random timing add nonce to the agent source
-     */
-    async function _Agent_selfLearnNonce() {
-        await waitasecond.forTime(Math.random() * 5000);
-        // <- TODO: [🕓] `await forRandom(...)`
-        console.info(colors__default["default"].bgCyan('[Self-learning]') + colors__default["default"].cyan(' Nonce'));
-        const nonce = `NONCE ${await linguisticHash(Math.random().toString())}`;
-        // Append to the current source
-        const currentSource = this.agentSource.value;
-        const newSource = padBook(validateBook(spaceTrim__default["default"](currentSource) + '\n\n---\n\n' + nonce));
-        // <- TODO: [🈲] Use some object-based way how to append on book (with sections `---`)
-        // Update the source (which will trigger the subscription and update the underlying tools)
-        this.agentSource.next(newSource);
-    }, _Agent_selfLearnSamples = function _Agent_selfLearnSamples(prompt, result) {
-        console.info(colors__default["default"].bgCyan('[Self-learning]') + colors__default["default"].cyan(' Sampling'));
-        const learningExample = spaceTrim__default["default"]((block) => `
-
-                USER MESSAGE
-                ${block(prompt.content)}
-
-                AGENT MESSAGE
-                ${block(result.content)}
-
-            `);
-        // Append to the current source
-        const currentSource = this.agentSource.value;
-        const newSource = padBook(validateBook(spaceTrim__default["default"](currentSource) + '\n\n---\n\n' + learningExample));
-        // <- TODO: [🈲] Use some object-based way how to append on book (with sections `---`)
-        // Update the source (which will trigger the subscription and update the underlying tools)
-        this.agentSource.next(newSource);
-    }, _Agent_selfLearnTeacher = 
-    /**
-     * Self-learning Step 2: Asynchronously call the teacher agent and invoke the silver link
-     */
-    async function _Agent_selfLearnTeacher(prompt, result) {
-        // [1] Call the teacher agent // <- !!!!! Emojis
-        if (this.teacherAgent === null) {
-            return null;
-        }
-        console.info(colors__default["default"].bgCyan('[Self-learning]') + colors__default["default"].cyan(' Teacher'));
-        const teacherResult = await this.teacherAgent.callChatModel({
-            title: 'Self-learning',
-            modelRequirements: {
-                modelVariant: 'CHAT',
-            },
-            // TODO: !!!! Use prompt notation
-            content: spaceTrim__default["default"]((block) => `
-
-                    You are a teacher agent helping another agent to learn from its interactions.
-
-                    Here is your current client which you are teaching:
-
-                    \`\`\`book
-                    ${block(this.agentSource.value)}
-                    \`\`\`
-
-                    **And here is the latest interaction:**
-
-                    **User:**
-                    ${block(prompt.content)}
-
-                    **Agent:**
-                    ${block(result.content)}
-
-
-                    **Rules:**
-
-                    - Decide what the agent should learn from this interaction.
-                    - Append new commitments at the end of the agent source.
-                    - Do not modify the current agent source, just return new commitments (KNOWLEDGE, RULE, etc.).
-                    - If there is nothing new to learn, return empty book code block
-                    - Wrap the commitments in a book code block.
-                    - Do not explain anything, just return the commitments wrapped in a book code block.
-                    - Write the learned commitments in the same style and language as in the original agent source.
-
-
-                    This is how book code block looks like:
-
-                    \`\`\`book
-                    KNOWLEDGE The sky is blue.
-                    RULE Always be polite.
-                    \`\`\`
-                `),
-            // pipelineUrl: 'https://github.com/webgptorg/promptbook/blob/main/prompts/self-learning.ptbk.md',
-            // <- TODO: !!!! Remove and `pipelineUrl` for agent purposes
-            parameters: {},
-        });
-        console.log('!!!! teacherResult', teacherResult);
-        const teacherCommitments = unwrapResult(teacherResult.content);
-        if (teacherCommitments === '') {
-            console.info(colors__default["default"].bgCyan('[Self-learning]') +
-                colors__default["default"].cyan(' Teacher agent did not provide new commitments to learn'));
-            return buildTeacherSummary('', true);
-        }
-        // [2] Append to the current source
-        const currentSource = this.agentSource.value;
-        const newSource = padBook(validateBook(spaceTrim__default["default"](currentSource) + '\n\n' + teacherCommitments));
-        // <- TODO: [🈲] Use some object-based way how to append on book (with sections `---`)
-        // [3] Update the source
-        this.agentSource.next(newSource);
-        return buildTeacherSummary(teacherCommitments, true);
-    };
     /**
      * TODO: [🧠][😰]Agent is not working with the parameters, should it be?
      */
@@ -26996,13 +27715,23 @@
             remoteAgent.samples = profile.samples || [];
             remoteAgent.toolTitles = profile.toolTitles || {};
             remoteAgent._isVoiceCallingEnabled = profile.isVoiceCallingEnabled === true; // [✨✷] Store voice calling status
+            remoteAgent._isVoiceTtsSttEnabled = profile.isVoiceTtsSttEnabled !== false;
             remoteAgent.knowledgeSources = profile.knowledgeSources || [];
             return remoteAgent;
         }
+        /**
+         * Indicates whether the remote server allows text-to-speech and speech-to-text.
+         *
+         * @public exported from `@promptbook/core`
+         */
+        get isVoiceTtsSttEnabled() {
+            return this._isVoiceTtsSttEnabled;
+        }
         constructor(options) {
             super(options);
             this.toolTitles = {};
             this._isVoiceCallingEnabled = false; // [✨✷] Track voice calling status
+            this._isVoiceTtsSttEnabled = true;
             this.knowledgeSources = [];
             this.agentUrl = options.agentUrl;
         }
@@ -27024,7 +27753,7 @@
          * Returns undefined if voice calling is disabled
          */
         get callVoiceChatModel() {
-            if (!this._isVoiceCallingEnabled) {
+            if (!this._isVoiceCallingEnabled || !this._isVoiceTtsSttEnabled) {
                 return undefined;
             }
             return async (audio, prompt) => {
@@ -27063,7 +27792,7 @@
                 };
             };
         }
-        async callChatModelStream(prompt, onProgress) {
+        async callChatModelStream(prompt, onProgress, options) {
             // Ensure we're working with a chat prompt
             if (prompt.modelRequirements.modelVariant !== 'CHAT') {
                 throw new Error('Agents only supports chat prompts');
@@ -27080,6 +27809,7 @@
                     attachments: chatPrompt.attachments,
                     parameters: chatPrompt.parameters,
                 }),
+                signal: options === null || options === void 0 ? void 0 : options.signal,
             });
             // <- TODO: [🐱‍🚀] What about closed-source agents?
             // <- TODO: [🐱‍🚀] Maybe use promptbookFetch
@@ -27087,6 +27817,7 @@
             const toolCalls = [];
             const preparationToolCalls = [];
             let hasReceivedModelOutput = false;
+            let pendingToolCallLineFragment = '';
             const normalizeToolCall = (toolCall) => {
                 if (toolCall.createdAt) {
                     return toolCall;
@@ -27139,6 +27870,113 @@
              * Builds the tool call list including any preparation marker still active.
              */
             const getActiveToolCalls = () => preparationToolCalls.length > 0 ? [...preparationToolCalls, ...toolCalls] : toolCalls;
+            /**
+             * Emits one progress snapshot using current aggregated text and tool calls.
+             */
+            const emitProgress = () => {
+                onProgress({
+                    content,
+                    modelName: this.modelName,
+                    timing: {},
+                    usage: {},
+                    rawPromptContent: {},
+                    rawRequest: {},
+                    rawResponse: {},
+                    toolCalls: getActiveToolCalls(),
+                });
+            };
+            /**
+             * Attempts to parse one completed NDJSON tool-call line.
+             */
+            const tryParseToolCallLine = (trimmedLine) => {
+                if (!trimmedLine.startsWith('{') || !trimmedLine.endsWith('}')) {
+                    return false;
+                }
+                try {
+                    const chunk = JSON.parse(trimmedLine);
+                    if (!chunk.toolCalls) {
+                        return false;
+                    }
+                    const normalizedToolCalls = chunk.toolCalls.map(normalizeToolCall);
+                    upsertToolCalls(normalizedToolCalls);
+                    emitProgress();
+                    return true;
+                }
+                catch (_a) {
+                    return false;
+                }
+            };
+            /**
+             * Detects whether an incomplete trailing line might be a split tool-call payload.
+             */
+            const isPotentialToolCallLineFragment = (trimmedLine) => {
+                if (trimmedLine.length === 0) {
+                    return false;
+                }
+                const toolCallPrefix = '{"toolCalls":';
+                return toolCallPrefix.startsWith(trimmedLine) || trimmedLine.startsWith(toolCallPrefix);
+            };
+            /**
+             * Appends model text to accumulated content and emits progress.
+             */
+            const appendTextChunk = (textChunk) => {
+                if (!textChunk) {
+                    return;
+                }
+                content += textChunk;
+                if (!hasReceivedModelOutput && content.trim().length > 0) {
+                    hasReceivedModelOutput = true;
+                    preparationToolCalls.length = 0;
+                }
+                emitProgress();
+            };
+            /**
+             * Consumes one decoded transport chunk, removing keep-alive pings and tool-call frames.
+             *
+             * Note: Tool-call JSON is line-delimited but may arrive split across transport chunks.
+             */
+            const processDecodedChunk = (decodedChunk) => {
+                var _a;
+                if (!decodedChunk) {
+                    return;
+                }
+                const combinedChunk = pendingToolCallLineFragment + decodedChunk;
+                pendingToolCallLineFragment = '';
+                const hasTrailingNewline = combinedChunk.endsWith('\n') || combinedChunk.endsWith('\r');
+                const lines = combinedChunk.split(/\r?\n/);
+                const trailingFragment = hasTrailingNewline ? '' : (_a = lines.pop()) !== null && _a !== void 0 ? _a : '';
+                let hasNonEmptyText = false;
+                const textLines = [];
+                for (const line of lines) {
+                    const trimmedLine = line.trim();
+                    if (trimmedLine === CHAT_STREAM_KEEP_ALIVE_TOKEN) {
+                        continue;
+                    }
+                    if (tryParseToolCallLine(trimmedLine)) {
+                        continue;
+                    }
+                    textLines.push(line);
+                    if (trimmedLine.length > 0) {
+                        hasNonEmptyText = true;
+                    }
+                }
+                if (trailingFragment !== '') {
+                    const trimmedTrailingFragment = trailingFragment.trim();
+                    if (isPotentialToolCallLineFragment(trimmedTrailingFragment)) {
+                        pendingToolCallLineFragment = trailingFragment;
+                    }
+                    else {
+                        textLines.push(trailingFragment);
+                        if (trimmedTrailingFragment.length > 0) {
+                            hasNonEmptyText = true;
+                        }
+                    }
+                }
+                if (!hasNonEmptyText) {
+                    return;
+                }
+                appendTextChunk(textLines.join('\n'));
+            };
             if (!bookResponse.body) {
                 content = await bookResponse.text();
             }
@@ -27154,92 +27992,26 @@
                         doneReading = !!done;
                         if (value) {
                             const textChunk = decoder.decode(value, { stream: true });
-                            let sawToolCalls = false;
-                            let hasNonEmptyText = false;
-                            const textLines = [];
-                            const lines = textChunk.split(/\r?\n/);
-                            for (const line of lines) {
-                                const trimmedLine = line.trim();
-                                if (trimmedLine === CHAT_STREAM_KEEP_ALIVE_TOKEN) {
-                                    continue;
-                                }
-                                let isToolCallLine = false;
-                                if (trimmedLine.startsWith('{') && trimmedLine.endsWith('}')) {
-                                    try {
-                                        const chunk = JSON.parse(trimmedLine);
-                                        if (chunk.toolCalls) {
-                                            const normalizedToolCalls = chunk.toolCalls.map(normalizeToolCall);
-                                            upsertToolCalls(normalizedToolCalls);
-                                            onProgress({
-                                                content,
-                                                modelName: this.modelName,
-                                                timing: {},
-                                                usage: {},
-                                                rawPromptContent: {},
-                                                rawRequest: {},
-                                                rawResponse: {},
-                                                toolCalls: getActiveToolCalls(),
-                                            });
-                                            sawToolCalls = true;
-                                            isToolCallLine = true;
-                                        }
-                                    }
-                                    catch (error) {
-                                        // Ignore non-json lines
-                                    }
-                                }
-                                if (!isToolCallLine) {
-                                    textLines.push(line);
-                                    if (line.length > 0) {
-                                        hasNonEmptyText = true;
-                                    }
-                                }
-                            }
-                            if (sawToolCalls) {
-                                if (!hasNonEmptyText) {
-                                    continue;
-                                }
-                                const textChunkWithoutToolCalls = textLines.join('\n');
-                                content += textChunkWithoutToolCalls;
-                            }
-                            else {
-                                // console.debug('RemoteAgent chunk:', textChunk);
-                                content += textChunk;
-                            }
-                            if (!hasReceivedModelOutput && content.trim().length > 0) {
-                                hasReceivedModelOutput = true;
-                                preparationToolCalls.length = 0;
-                            }
-                            onProgress({
-                                content,
-                                modelName: this.modelName,
-                                timing: {},
-                                usage: {},
-                                rawPromptContent: {},
-                                rawRequest: {},
-                                rawResponse: {},
-                                toolCalls: getActiveToolCalls(),
-                            });
+                            processDecodedChunk(textChunk);
                         }
                     }
                     // Flush any remaining decoder internal state
                     const lastChunk = decoder.decode();
                     if (lastChunk) {
-                        content += lastChunk;
-                        if (!hasReceivedModelOutput && content.trim().length > 0) {
-                            hasReceivedModelOutput = true;
-                            preparationToolCalls.length = 0;
+                        processDecodedChunk(lastChunk);
+                    }
+                    if (pendingToolCallLineFragment) {
+                        const trimmedPending = pendingToolCallLineFragment.trim();
+                        if (trimmedPending === CHAT_STREAM_KEEP_ALIVE_TOKEN) {
+                            pendingToolCallLineFragment = '';
+                        }
+                        else if (tryParseToolCallLine(trimmedPending)) {
+                            pendingToolCallLineFragment = '';
+                        }
+                        else {
+                            appendTextChunk(pendingToolCallLineFragment);
+                            pendingToolCallLineFragment = '';
                         }
-                        onProgress({
-                            content: lastChunk,
-                            modelName: this.modelName,
-                            timing: {},
-                            usage: {},
-                            rawPromptContent: {},
-                            rawRequest: {},
-                            rawResponse: {},
-                            toolCalls: getActiveToolCalls(),
-                        });
                     }
                 }
                 finally {