@promptbook/cli 0.111.0-0 → 0.111.0-10

package/esm/index.es.js

@@ -48,7 +48,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @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
@@ -309,6 +309,188 @@ function checkChannelValue(channelName, value) {
     }
 }
 
+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
  *
@@ -389,29 +571,24 @@ class Color {
      * @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}".`);
         }
     }
     /**
@@ -442,73 +619,8 @@ class Color {
      * @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
@@ -517,52 +629,8 @@ class Color {
      * @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
@@ -571,25 +639,8 @@ class Color {
      * @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
@@ -598,39 +649,8 @@ class Color {
      * @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
@@ -774,22 +794,6 @@ class Color {
         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
@@ -2557,6 +2561,12 @@ const RESERVED_PARAMETER_NAMES = exportJson({
         // <- 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
  *
@@ -3284,6 +3294,19 @@ class CollectionError extends Error {
     }
 }
 
+/**
+ * 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
  *
@@ -3503,6 +3526,7 @@ const PROMPTBOOK_ERRORS = {
     WrappedError,
     NotAllowed,
     DatabaseError,
+    ConflictError,
     // TODO: [🪑]> VersionMismatchError,
 };
 /**
@@ -4177,13 +4201,29 @@ function templateParameters(template, parameters) {
     return replacedTemplates;
 }
 
+/**
+ * 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 {
@@ -4195,59 +4235,27 @@ function normalizeJsonString(value) {
 }
 /**
  * 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() === '') {
@@ -4256,10 +4264,11 @@ function shouldInlineParameterValue(value) {
     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
@@ -4268,17 +4277,32 @@ function escapePromptParameterValue(value, options) {
     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';
@@ -4294,6 +4318,7 @@ function buildAlphabeticParameterName(index) {
  * Converts a positive integer into a Roman numeral string.
  *
  * @param value Positive integer value.
+ * @private function of ParameterNaming
  */
 function toRomanNumeral(value) {
     const romanTable = [
@@ -4322,24 +4347,28 @@ function toRomanNumeral(value) {
     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 },
@@ -4352,6 +4381,7 @@ const PARAMETER_NAME_STRATEGIES = [
  * 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();
@@ -4368,9 +4398,10 @@ function collectBracketedParameterTokens(values) {
     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;
@@ -4387,28 +4418,40 @@ function buildParameterNames(values) {
     }
     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
@@ -4423,6 +4466,55 @@ function buildParametersSection(items) {
             - 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
  *
@@ -4440,24 +4532,24 @@ function prompt(strings, ...values) {
     if (values.length === 0) {
         return new PromptString(spaceTrim$2(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,
@@ -4477,7 +4569,7 @@ function prompt(strings, ...values) {
         const parameterName = parameterNamesOrdered[i];
         return parameterName === undefined
             ? `${result}${stringsItem}`
-            : `${result}${stringsItem}${formatParameterPlaceholder(parameterName)}`;
+            : `${result}${stringsItem}${ParameterSection.formatParameterPlaceholder(parameterName)}`;
     }, '');
     pipelineString = spaceTrim$2(pipelineString);
     try {
@@ -4495,14 +4587,16 @@ function prompt(strings, ...values) {
                   
                 `));
     }
-    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);
@@ -4512,7 +4606,7 @@ function prompt(strings, ...values) {
             value: entry.stringValue,
             jsonValue: entry.jsonValue,
         }));
-        pipelineString = `${pipelineString}\n\n${buildParametersSection(parameterItems)}`;
+        pipelineString = `${pipelineString}\n\n${ParameterSection.buildParametersSection(parameterItems)}`;
     }
     return new PromptString(pipelineString);
 }
@@ -16704,6 +16798,91 @@ class ImportCommitmentDefinition extends BaseCommitmentDefinition {
  * Note: [💞] Ignore a discrepancy between file name and entity name
  */
 
+/** @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 = /[.,!?;:'"`]+$/;
+/**
+ * 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 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 urls;
+}
+/**
+ * @private Normalizes one extracted URL candidate by stripping trailing punctuation and unmatched closing wrappers.
+ */
+function normalizeUrlCandidate(candidate) {
+    let normalized = candidate.trim();
+    if (!normalized) {
+        return '';
+    }
+    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 */
@@ -16901,43 +17080,58 @@ class KnowledgeCommitmentDefinition extends BaseCommitmentDefinition {
         `);
     }
     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
@@ -17113,6 +17307,7 @@ function resolveMemoryRuntimeContext(args) {
         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,
     };
 }
 /**
@@ -17158,12 +17353,15 @@ function createDisabledMemoryResult(action, message) {
  * @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),
         };
     }
     {
@@ -17886,6 +18084,72 @@ class UserMessageCommitmentDefinition extends BaseCommitmentDefinition {
     }
 }
 
+/**
+ * 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(`
+            # 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
  *
@@ -18127,6 +18391,76 @@ class MetaColorCommitmentDefinition extends BaseCommitmentDefinition {
  * 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(`
+            # 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
  *
@@ -18408,6 +18742,77 @@ class MetaLinkCommitmentDefinition extends BaseCommitmentDefinition {
  * 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(`
+            # 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
  *
@@ -18766,7 +19171,7 @@ class OpenCommitmentDefinition extends BaseCommitmentDefinition {
      * 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.
@@ -20476,8 +20881,8 @@ class UseEmailCommitmentDefinition extends BaseCommitmentDefinition {
 /**
  * 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:
  *
@@ -20490,13 +20895,16 @@ class UseEmailCommitmentDefinition extends BaseCommitmentDefinition {
  */
 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.
@@ -20511,21 +20919,21 @@ class UseImageGeneratorCommitmentDefinition extends BaseCommitmentDefinition {
         return spaceTrim$1(`
             # 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.
             \`\`\`
@@ -20535,80 +20943,28 @@ class UseImageGeneratorCommitmentDefinition extends BaseCommitmentDefinition {
 
             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(`
-                        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(`
-                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((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)}
+                `));
     }
 }
 /**
@@ -21072,6 +21428,221 @@ class UseTimeCommitmentDefinition extends BaseCommitmentDefinition {
  * 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(`
+            # 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(`
+                          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((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
  *
@@ -21139,6 +21710,7 @@ class NotYetImplementedCommitmentDefinition extends BaseCommitmentDefinition {
     }
 }
 
+// Import all commitment definition classes
 /**
  * Registry of all available commitment definitions
  * This array contains instances of all commitment definitions
@@ -21177,7 +21749,9 @@ const COMMITMENT_REGISTRY = [
     new MetaColorCommitmentDefinition(),
     new MetaFontCommitmentDefinition(),
     new MetaLinkCommitmentDefinition(),
+    new MetaDisclaimerCommitmentDefinition(),
     new MetaCommitmentDefinition(),
+    new MetaVoiceCommitmentDefinition(),
     new NoteCommitmentDefinition('NOTE'),
     new NoteCommitmentDefinition('NOTES'),
     new NoteCommitmentDefinition('COMMENT'),
@@ -21188,6 +21762,7 @@ const COMMITMENT_REGISTRY = [
     new InitialMessageCommitmentDefinition(),
     new UserMessageCommitmentDefinition(),
     new AgentMessageCommitmentDefinition(),
+    new MessageSuffixCommitmentDefinition(),
     new MessageCommitmentDefinition('MESSAGE'),
     new MessageCommitmentDefinition('MESSAGES'),
     new ScenarioCommitmentDefinition('SCENARIO'),
@@ -21203,13 +21778,9 @@ const COMMITMENT_REGISTRY = [
     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)
@@ -27808,17 +28379,17 @@ class OpenAiCompatibleExecutionTools {
     /**
      * 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 });
@@ -28110,7 +28681,7 @@ class OpenAiCompatibleExecutionTools {
                 });
                 // 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}`);
@@ -30023,7 +30594,7 @@ class OpenAiAssistantExecutionTools extends OpenAiVectorStoreHandler {
     /**
      * 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 });
@@ -32503,6 +33074,7 @@ function parseAgentSource(agentSource) {
     const capabilities = [];
     const samples = [];
     const knowledgeSources = [];
+    const knownKnowledgeSourceUrls = new Set();
     let pendingUserMessage = null;
     for (const commitment of parseResult.commitments) {
         if (commitment.type === 'INITIAL MESSAGE') {
@@ -32552,6 +33124,14 @@ function parseAgentSource(agentSource) {
             });
             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',
@@ -32630,21 +33210,34 @@ function parseAgentSource(agentSource) {
             continue;
         }
         if (commitment.type === 'KNOWLEDGE') {
-            const content = spaceTrim$2(commitment.content).split(/\r?\n/)[0] || '';
+            const content = spaceTrim$2(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 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 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 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';
@@ -32653,6 +33246,9 @@ function parseAgentSource(agentSource) {
                     else {
                         label = url.hostname.replace(/^www\./, '');
                     }
+                    if (extractedUrls.length > 1) {
+                        label = `${label} (+${extractedUrls.length - 1})`;
+                    }
                 }
                 catch (e) {
                     // Invalid URL, treat as text
@@ -32686,6 +33282,14 @@ function parseAgentSource(agentSource) {
             meta.description = spaceTrim$2(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;
@@ -32694,6 +33298,10 @@ function parseAgentSource(agentSource) {
             meta.font = normalizeSeparator(commitment.content);
             continue;
         }
+        if (commitment.type === 'META VOICE') {
+            meta.voice = spaceTrim$2(commitment.content);
+            continue;
+        }
         if (commitment.type !== 'META') {
             continue;
         }
@@ -33298,27 +33906,6 @@ function getToolCallIdentity(toolCall) {
     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);
-}
-
 /**
  * Gets all tool titles provided by all commitments
  *
@@ -33611,7 +34198,7 @@ class OpenAiAgentKitExecutionTools extends OpenAiVectorStoreHandler {
     /**
      * 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');
@@ -33638,6 +34225,7 @@ class OpenAiAgentKitExecutionTools extends OpenAiVectorStoreHandler {
             rawPromptContent,
             onProgress,
             responseFormatOutputType,
+            signal: options === null || options === void 0 ? void 0 : options.signal,
         });
     }
     /**
@@ -33836,6 +34424,7 @@ class OpenAiAgentKitExecutionTools extends OpenAiVectorStoreHandler {
         const streamResult = await 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') {
@@ -34031,6 +34620,24 @@ function emitAssistantPreparationProgress(options) {
         ],
     });
 }
+/**
+ * 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
@@ -34174,8 +34781,8 @@ class AgentLlmExecutionTools {
     /**
      * 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');
@@ -34183,6 +34790,14 @@ class AgentLlmExecutionTools {
         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}`
@@ -34198,9 +34813,7 @@ class AgentLlmExecutionTools {
                     ? [...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
@@ -34210,27 +34823,34 @@ class AgentLlmExecutionTools {
         };
         console.log('!!!! promptWithAgentModelRequirements:', promptWithAgentModelRequirements);
         if (OpenAiAgentKitExecutionTools.isOpenAiAgentKitExecutionTools(this.options.llmTools)) {
-            const requirementsHash = SHA256(JSON.stringify(sanitizedRequirements)).toString();
-            const vectorStoreHash = 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 = SHA256(JSON.stringify(sanitizedRequirements)).toString();
+                vectorStoreHash = 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) {
@@ -34238,7 +34858,7 @@ class AgentLlmExecutionTools {
                         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,
@@ -34255,28 +34875,31 @@ class AgentLlmExecutionTools {
                 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)) {
@@ -34374,14 +34997,14 @@ class AgentLlmExecutionTools {
                 },
             };
             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);
@@ -34427,9 +35050,179 @@ AgentLlmExecutionTools.vectorStoreCache = new Map();
  * 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(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.bgCyan('[Self-learning]') + colors.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 forTime(Math.random() * 5000);
+        console.info(colors.bgCyan('[Self-learning]') + colors.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.bgCyan('[Self-learning]') + colors.cyan(' Sampling'));
+        const learningExample = spaceTrim$2((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.bgCyan('[Self-learning]') + colors.cyan(' Teacher'));
+        const teacherInstructions = extractOpenTeacherInstructions(this.options.getAgentSource());
+        const teacherInstructionsSection = teacherInstructions
+            ? spaceTrim$2((block) => `
+                      **Teacher instructions:**
+                      ${block(teacherInstructions)}
+                  `)
+            : '';
+        const teacherPromptContent = spaceTrim$2((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.bgCyan('[Self-learning]') +
+                colors.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$2(currentSource) + section));
+        this.options.updateAgentSource(newSource);
+    }
+}
 /**
  * Creates an empty commitment breakdown for self-learning summaries.
+ *
+ * @private function of Agent
  */
 function createEmptySelfLearningCommitmentCounts() {
     return {
@@ -34442,6 +35235,9 @@ function createEmptySelfLearningCommitmentCounts() {
 }
 /**
  * Normalizes teacher commitments into trimmed, display-ready lines.
+ *
+ * @param commitments Raw teacher output
+ * @private function of Agent
  */
 function getTeacherCommitmentLines(commitments) {
     return commitments
@@ -34451,6 +35247,9 @@ function getTeacherCommitmentLines(commitments) {
 }
 /**
  * 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;
@@ -34478,6 +35277,11 @@ function summarizeTeacherCommitmentLines(lines) {
 }
 /**
  * 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);
@@ -34487,6 +35291,34 @@ function buildTeacherSummary(commitments, used) {
         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
  *
@@ -34529,7 +35361,6 @@ class Agent extends AgentLlmExecutionTools {
             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
@@ -34568,8 +35399,12 @@ class Agent extends AgentLlmExecutionTools {
         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);
@@ -34592,7 +35427,8 @@ class Agent extends AgentLlmExecutionTools {
      *
      * 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) {
@@ -34636,13 +35472,17 @@ class Agent extends AgentLlmExecutionTools {
                 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',
@@ -34654,24 +35494,7 @@ class Agent extends AgentLlmExecutionTools {
             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.bgCyan('[Self-learning]') + colors.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 = {
@@ -34693,110 +35516,6 @@ class Agent extends AgentLlmExecutionTools {
         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 forTime(Math.random() * 5000);
-    // <- TODO: [🕓] `await forRandom(...)`
-    console.info(colors.bgCyan('[Self-learning]') + colors.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$2(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.bgCyan('[Self-learning]') + colors.cyan(' Sampling'));
-    const learningExample = spaceTrim$2((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$2(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.bgCyan('[Self-learning]') + colors.cyan(' Teacher'));
-    const teacherResult = await this.teacherAgent.callChatModel({
-        title: 'Self-learning',
-        modelRequirements: {
-            modelVariant: 'CHAT',
-        },
-        // TODO: !!!! Use prompt notation
-        content: spaceTrim$2((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.bgCyan('[Self-learning]') +
-            colors.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$2(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?
  */
@@ -34947,13 +35666,23 @@ class RemoteAgent extends Agent {
         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;
     }
@@ -34975,7 +35704,7 @@ class RemoteAgent extends Agent {
      * Returns undefined if voice calling is disabled
      */
     get callVoiceChatModel() {
-        if (!this._isVoiceCallingEnabled) {
+        if (!this._isVoiceCallingEnabled || !this._isVoiceTtsSttEnabled) {
             return undefined;
         }
         return async (audio, prompt) => {
@@ -35014,7 +35743,7 @@ class RemoteAgent extends Agent {
             };
         };
     }
-    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');
@@ -35031,6 +35760,7 @@ class RemoteAgent extends Agent {
                 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
@@ -35038,6 +35768,7 @@ class RemoteAgent extends Agent {
         const toolCalls = [];
         const preparationToolCalls = [];
         let hasReceivedModelOutput = false;
+        let pendingToolCallLineFragment = '';
         const normalizeToolCall = (toolCall) => {
             if (toolCall.createdAt) {
                 return toolCall;
@@ -35090,6 +35821,113 @@ class RemoteAgent extends Agent {
          * 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();
         }
@@ -35105,92 +35943,26 @@ class RemoteAgent extends Agent {
                     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 {