@promptbook/wizard 0.106.0-0 → 0.108.0-0

package/esm/index.es.js

@@ -37,7 +37,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.106.0-0';
+const PROMPTBOOK_ENGINE_VERSION = '0.108.0-0';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -6252,13 +6252,125 @@ function escapePromptParameterValue(value, options) {
     return value.replace(pattern, '\\$&');
 }
 /**
- * Builds the parameter name used in prompt placeholders.
+ * Builds numeric parameter name used in prompt placeholders.
  *
  * @param index Zero-based parameter index.
  */
-function buildParameterName(index) {
+function buildNumericParameterName(index) {
     return `${index + 1}`;
 }
+/**
+ * Builds alphabetic parameter name used in prompt placeholders.
+ *
+ * @param index Zero-based parameter index.
+ */
+function buildAlphabeticParameterName(index) {
+    const alphabet = 'abcdefghijklmnopqrstuvwxyz';
+    let result = '';
+    let remaining = index;
+    while (remaining >= 0) {
+        result = alphabet[remaining % alphabet.length] + result;
+        remaining = Math.floor(remaining / alphabet.length) - 1;
+    }
+    return result;
+}
+/**
+ * Converts a positive integer into a Roman numeral string.
+ *
+ * @param value Positive integer value.
+ */
+function toRomanNumeral(value) {
+    const romanTable = [
+        { symbol: 'M', value: 1000 },
+        { symbol: 'CM', value: 900 },
+        { symbol: 'D', value: 500 },
+        { symbol: 'CD', value: 400 },
+        { symbol: 'C', value: 100 },
+        { symbol: 'XC', value: 90 },
+        { symbol: 'L', value: 50 },
+        { symbol: 'XL', value: 40 },
+        { symbol: 'X', value: 10 },
+        { symbol: 'IX', value: 9 },
+        { symbol: 'V', value: 5 },
+        { symbol: 'IV', value: 4 },
+        { symbol: 'I', value: 1 },
+    ];
+    let remaining = Math.max(1, Math.floor(value));
+    let result = '';
+    for (const entry of romanTable) {
+        while (remaining >= entry.value) {
+            result += entry.symbol;
+            remaining -= entry.value;
+        }
+    }
+    return result;
+}
+/**
+ * Builds Roman numeral parameter name used in prompt placeholders.
+ *
+ * @param index Zero-based parameter index.
+ */
+function buildRomanParameterName(index) {
+    return toRomanNumeral(index + 1);
+}
+/**
+ * Creates a parameter name builder that prefixes another builder.
+ *
+ * @param prefix Prefix to add.
+ * @param builder Base builder to wrap.
+ */
+function buildPrefixedParameterName(prefix, builder) {
+    return (index) => `${prefix}${builder(index)}`;
+}
+/**
+ * Ordered list of strategies for parameter naming.
+ */
+const PARAMETER_NAME_STRATEGIES = [
+    { buildName: buildNumericParameterName },
+    { buildName: buildAlphabeticParameterName },
+    { buildName: buildRomanParameterName },
+    { buildName: buildPrefixedParameterName('p', buildNumericParameterName) },
+    { buildName: buildPrefixedParameterName('p', buildAlphabeticParameterName) },
+];
+/**
+ * Collects bracketed tokens from parameter values to avoid placeholder collisions.
+ *
+ * @param values Parameter values to scan.
+ */
+function collectBracketedParameterTokens(values) {
+    const tokens = new Set();
+    for (const value of values) {
+        const pattern = /{(\w+)}/g;
+        let match;
+        while ((match = pattern.exec(value)) !== null) {
+            const token = match[1];
+            if (token) {
+                tokens.add(token);
+            }
+        }
+    }
+    return tokens;
+}
+/**
+ * Builds parameter names used in prompt placeholders while avoiding collisions.
+ *
+ * @param values Parameter values to scan for conflicting tokens.
+ */
+function buildParameterNames(values) {
+    const count = values.length;
+    if (count === 0) {
+        return [];
+    }
+    const conflicts = collectBracketedParameterTokens(values);
+    for (const strategy of PARAMETER_NAME_STRATEGIES) {
+        const names = Array.from({ length: count }, (_, index) => strategy.buildName(index));
+        const hasConflict = names.some((name) => conflicts.has(name));
+        if (!hasConflict) {
+            return names;
+        }
+    }
+    return Array.from({ length: count }, (_, index) => `${REPLACING_NONCE}${index + 1}`);
+}
 /**
  * Formats the placeholder used in the prompt body for a parameter.
  *
@@ -6313,26 +6425,40 @@ function prompt(strings, ...values) {
         return new PromptString(spaceTrim$2(strings.join('')));
     }
     const stringsWithHiddenParameters = strings.map((stringsItem) => hideBrackets(stringsItem));
-    const parameterEntries = values.map((value, index) => {
-        const name = buildParameterName(index);
+    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;
+        return { isPrompt, stringValue, isInline, jsonValue };
+    });
+    const parameterNames = 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 promptMarker = `${REPLACING_NONCE}prompt-${index}`;
         const parameterMarker = `${REPLACING_NONCE}parameter-${index}`;
-        const templateValue = isPrompt
+        const templateValue = entry.isPrompt
             ? promptMarker
-            : isInline
-                ? escapePromptParameterValue(stringValue, { includeBraces: false })
+            : entry.isInline
+                ? escapePromptParameterValue(entry.stringValue, { includeBraces: false })
                 : parameterMarker;
-        return { name, stringValue, jsonValue, isPrompt, isInline, promptMarker, parameterMarker, templateValue };
+        return {
+            name,
+            stringValue: entry.stringValue,
+            jsonValue: entry.jsonValue,
+            isPrompt: entry.isPrompt,
+            isInline: entry.isInline,
+            promptMarker,
+            parameterMarker,
+            templateValue,
+        };
     });
     const parameters = Object.fromEntries(parameterEntries.map((entry) => [entry.name, entry.templateValue]));
-    const parameterNames = parameterEntries.map((entry) => entry.name);
+    const parameterNamesOrdered = parameterEntries.map((entry) => entry.name);
     // Combine strings and values
     let pipelineString = stringsWithHiddenParameters.reduce((result, stringsItem, i) => {
-        const parameterName = parameterNames[i];
+        const parameterName = parameterNamesOrdered[i];
         return parameterName === undefined
             ? `${result}${stringsItem}`
             : `${result}${stringsItem}${formatParameterPlaceholder(parameterName)}`;
@@ -6345,7 +6471,7 @@ function prompt(strings, ...values) {
         if (!(error instanceof PipelineExecutionError)) {
             throw error;
         }
-        console.error({ pipelineString, parameters, parameterNames, error });
+        console.error({ pipelineString, parameters, parameterNames: parameterNamesOrdered, error });
         throw new UnexpectedError(spaceTrim$2((block) => `
                     Internal error in prompt template literal
                   
@@ -6360,9 +6486,7 @@ function prompt(strings, ...values) {
             continue;
         }
         if (!entry.isInline) {
-            pipelineString = pipelineString
-                .split(entry.parameterMarker)
-                .join(formatParameterPlaceholder(entry.name));
+            pipelineString = pipelineString.split(entry.parameterMarker).join(formatParameterPlaceholder(entry.name));
         }
     }
     const structuredParameters = parameterEntries.filter((entry) => !entry.isPrompt && !entry.isInline);
@@ -6442,103 +6566,564 @@ function capitalize(word) {
     return word.substring(0, 1).toUpperCase() + word.substring(1);
 }
 
+// spell-checker: disable
 /**
- * Creates a human-readable hash as a short story sentence.
+ * @@@
  *
- * @public exported from `@promptbook/utils`
- */
-async function linguisticHash(input) {
-    const hash = computeHash(input);
-    return capitalize(createStorySentence(hash));
-}
-const HASH_SEGMENT_LENGTH = 8;
-const STORY_OPENERS = [
-    'once',
-    'long ago',
-    'at dawn',
-    'at dusk',
-    'suddenly',
-    'quietly',
-    'meanwhile',
-    'today',
-    'tonight',
-    'in the end',
-    'before long',
-    'for a moment',
+ * @private utility of `linguisticHash`
+ */
+const ADJECTIVES$1 = [
+    'červený',
+    'modrý',
+    'zelený',
+    'žlutý',
+    'rychlý',
+    'pomalý',
+    'jasný',
+    'temný',
+    'veselý',
+    'smutný',
+    'statečný',
+    'klidný',
+    'chytrý',
+    'bystrý',
+    'dychtivý',
+    'honosný',
+    'velkolepý',
+    'hravý',
+    'laskavý',
+    'šťastný',
+    'hrdý',
+    'pošetilý',
+    'moudrý',
+    'mladý',
+    'starý',
+    'veliký',
+    'malý',
+    'drobný',
+    'obrovský',
+    'krátký',
+    'dlouhý',
+    'blízký',
+    'vzdálený',
+    'vnitřní',
+    'vnější',
+    'trpělivý',
+    'stálý',
+    'ušlechtilý',
+    'čistý',
+    'špinavý',
+    'čerstvý',
+    'zvětralý',
+    'ostrý',
+    'tupý',
+    'tlustý',
+    'tenký',
+    'široký',
+    'úzký',
+    'hluboký',
+    'mělký',
+    'mocný',
+    'jemný',
+    'divoký',
+    'tichý',
+    'hlučný',
+    'pokojný',
+    'rušný',
+    'prázdný',
+    'plný',
+    'kulatý',
+    'hranatý',
+    'plochý',
+    'křivý',
+    'tvrdý',
+    'měkký',
+    'teplý',
+    'chladný',
+    'sladký',
+    'kyselý',
+    'hořký',
+    'slaný',
+    'silný',
+    'slabý',
+    'pevný',
+    'pružný',
+    'křehký',
+    'houževnatý',
+    'lesklý',
+    'matný',
+    'kluzký',
+    'lepkavý',
+    'svěží',
+    'vybledlý',
+    'mlhavý',
+    'bouřlivý',
+    'slunný',
+    'větrný',
+    'deštivý',
+    'mrazivý',
+    'zlatý',
+    'stříbrný',
+    'ledový',
+    'žhavý',
+    'prastarý',
+    'moderní',
+    'skrytý',
+    'ztracený',
+    'nalezený',
+    'magický',
+    'tajemný',
+    'kosmický',
+    'hvězdný',
+    'měsíční',
+    'sluneční',
+    'mlžný',
+    'ranní',
+    'večerní',
+    'noční',
+    'denní',
+    'osamělý',
+    'společenský',
+    'soukromý',
+    'veřejný',
+    'tajný',
+    'slavný',
+    'jistý',
+    'neurčitý',
+    'prostý',
+    'snadný',
+    'krotký',
+    'mírný',
+    'horký',
+    'suchý',
+    'mokrý',
+    'vlhký',
+    'promočený',
+    'vyprahlý',
+    'hladový',
+    'žíznivý',
+    'ospalý',
+    'bdělý',
+    'unavený',
+    'líný',
+    'neklidný',
+    'nestálý',
+    'odvážný',
+    'bázlivý',
+    'upřímný',
+    'věrný',
+    'pravý',
+    'falešný',
+    'spravedlivý',
+    'jednoduchý',
+    'složitý',
+    'přirozený',
+    'umělý',
+    'živý',
+    'mrtvý',
+    'zvídavý',
+    'zvláštní',
+    'běžný',
+    'vzácný',
+    'jedinečný',
+    'základní',
+    'prvotní',
+    'hbitý',
 ];
-const STORY_CONNECTORS = ['while', 'as', 'when', 'because', 'and', 'just as', 'after', 'before'];
-const STORY_PREPOSITIONS = [
-    'near',
-    'beside',
-    'under',
-    'within',
-    'beyond',
-    'around',
-    'behind',
-    'across',
-    'above',
-    'beneath',
-    'over',
-    'inside',
-    'outside',
-    'along',
+const NOUNS$1 = [
+    'jablko',
+    'nebe',
+    'strom',
+    'liška',
+    'kočka',
+    'pták',
+    'pes',
+    'řeka',
+    'hora',
+    'les',
+    'oceán',
+    'hvězda',
+    'měsíc',
+    'slunce',
+    'mrak',
+    'květ',
+    'list',
+    'kámen',
+    'vítr',
+    'déšť',
+    'oheň',
+    'led',
+    'kniha',
+    'sen',
+    'píseň',
+    'cesta',
+    'brána',
+    'klíč',
+    'lampa',
+    'mapa',
+    'dům',
+    'město',
+    'most',
+    'pole',
+    'zahrada',
+    'jezero',
+    'pláž',
+    'ostrov',
+    'údolí',
+    'poušť',
+    'svět',
+    'duch',
+    'srdce',
+    'mysl',
+    'duše',
+    'život',
+    'čas',
+    'prostor',
+    'světlo',
+    'stín',
+    'zvuk',
+    'hudba',
+    'hlas',
+    'slovo',
+    'stránka',
+    'příběh',
+    'perla',
+    'zlato',
+    'stříbro',
+    'krystal',
+    'diamant',
+    'smaragd',
+    'rubín',
+    'stezka',
+    'vrchol',
+    'břeh',
+    'vlna',
+    'příliv',
+    'plamen',
+    'jiskra',
+    'paprsek',
+    'semínko',
+    'kořen',
+    'větev',
+    'pupen',
+    'trn',
+    'kůra',
+    'skořápka',
+    'pírko',
+    'křídlo',
+    'dráp',
+    'tlapa',
+    'hnízdo',
+    'jeskyně',
+    'hájek',
+    'věž',
+    'hrad',
+    'koruna',
+    'meč',
+    'štít',
+    'mince',
+    'drahokam',
+    'prsten',
+    'zvonek',
+    'hodiny',
+    'kompas',
+    'kotva',
+    'pochodeň',
+    'flétna',
+    'harfa',
+    'buben',
+    'čočka',
+    'sklo',
+    'písek',
+    'prach',
+    'mlha',
+    'rosa',
+    'svítání',
+    'soumrak',
+    'noc',
+    'den',
+    'rok',
+    'věk',
+    'blesk',
+    'kapka',
+    'bouře',
+    'sníh',
+    'kroupa',
+    'kouř',
+    'pára',
+    'plyn',
+    'kov',
+    'skála',
+    'hlína',
+    'sůl',
+    'cukr',
+    'dřevo',
+    'kost',
+    'kůže',
+    'tělo',
+    'krev',
+    'buňka',
+    'atom',
+    'tep',
+    'dech',
+    'vzdech',
+    'jméno',
+    'ozvěna',
+    'obraz',
+    'vize',
+    'myšlenka',
+    'nápad',
+    'plán',
+    'cíl',
+    'přání',
+    'naděje',
+    'strach',
+    'radost',
+    'láska',
+    'nenávist',
+    'vůle',
+    'síla',
+    'energie',
+    'pohyb',
+    'rychlost',
+    'místo',
+    'bod',
+    'linie',
+    'tvar',
+    'forma',
+    'velikost',
+    'hmota',
+    'váha',
+    'teplo',
+    'chlad',
+    'barva',
+    'tón',
+    'rytmus',
+    'nálada',
+    'stav',
+    'krok',
+    'pád',
+    'skok',
+    'běh',
+    'let',
+    'klid',
+    'úkol',
+    'práce',
+    'hra',
+    'sport',
+    'umění',
+    'řemeslo',
+    'nástroj',
+    'loď',
+    'člun',
+    'auto',
+    'kolo',
+    'vlak',
+    'letadlo',
+    'uzel',
+    'síť',
+    'krabice',
+    'taška',
+    'dóza',
+    'hrnek',
+    'miska',
+    'talíř',
+    'lžíce',
+    'vidlička',
+    'nůž',
+    'pánev',
+    'hrnec',
+    'postel',
+    'stůl',
+    'židle',
+    'dveře',
+    'stěna',
+    'střecha',
+    'podlaha',
+    'okno',
+    'chodba',
 ];
-const STORY_TEMPLATES = [
-    (parts) => `${parts.opener}, the ${parts.adjective1} ${parts.noun1} was ${parts.verb1} ${parts.connector} the ${parts.adjective2} ${parts.noun2} was ${parts.verb2} ${parts.preposition} the ${parts.adjective3} ${parts.noun3}.`,
-    (parts) => `${parts.opener}, the ${parts.adjective1} ${parts.noun1} was ${parts.verb1} ${parts.preposition} the ${parts.adjective2} ${parts.noun2}, and the ${parts.adjective3} ${parts.noun3} was ${parts.verb2}.`,
-    (parts) => `${parts.opener}, the ${parts.adjective1} ${parts.noun1} was ${parts.verb1}, and the ${parts.adjective2} ${parts.noun2} was ${parts.verb2} ${parts.preposition} the ${parts.adjective3} ${parts.noun3}.`,
-    (parts) => `${parts.opener}, the ${parts.adjective1} ${parts.noun1} was ${parts.verb1} ${parts.connector} the ${parts.adjective2} ${parts.noun2} was ${parts.verb2}, ${parts.preposition} the ${parts.adjective3} ${parts.noun3}.`,
+const VERBS$1 = [
+    'skáče',
+    'tančí',
+    'letí',
+    'běží',
+    'zpívá',
+    'svítí',
+    'roste',
+    'plyne',
+    'padá',
+    'stoupá',
+    'spí',
+    'kráčí',
+    'mluví',
+    'myslí',
+    'sní',
+    'hledá',
+    'nachází',
+    'dává',
+    'bere',
+    'tvoří',
+    'hoří',
+    'mrzne',
+    'taje',
+    'dýchá',
+    'pulzuje',
+    'bije',
+    'žije',
+    'učí',
+    'ví',
+    'skrývá',
+    'ukazuje',
+    'láme',
+    'opravuje',
+    'ztrácí',
+    'nalézá',
+    'začíná',
+    'končí',
+    'plave',
+    'pluje',
+    'klouže',
+    'točí',
+    'mění',
+    'bledne',
+    'mizí',
+    'rodí',
+    'hučí',
+    'pláče',
+    'závodí',
+    'plíží',
+    'sleduje',
+    'slyší',
+    'cítí',
+    'touží',
+    'doufá',
+    'miluje',
+    'bloudí',
+    'putuje',
+    'cestuje',
+    'překračuje',
+    'potkává',
+    'drží',
+    'sdílí',
+    'jiskří',
+    'plápolá',
+    'léčí',
+    'řeší',
+    'otevírá',
+    'zavírá',
+    'zvedá',
+    'táhne',
+    'tlačí',
+    'hází',
+    'chytá',
+    'dělá',
+    'vidí',
+    'chutná',
+    'voní',
+    'spěchá',
+    'zastaví',
+    'jde',
+    'přichází',
+    'odchází',
+    'jedná',
+    'existuje',
+    'zmenšuje',
+    'rozšiřuje',
+    'zužuje',
+    'hřeje',
+    'chladí',
+    'suší',
+    'máčí',
+    'plní',
+    'vyprazdňuje',
+    'pouští',
+    'získává',
+    'vítězí',
+    'selhává',
+    'zkouší',
+    'používá',
+    'dostává',
+    'měří',
+    'stojí',
+    'dosahuje',
+    'míjí',
+    'udeří',
+    'vede',
+    'následuje',
+    'pomáhá',
+    'slouží',
+    'trénuje',
+    'kóduje',
+    'píše',
+    'čte',
+    'kreslí',
+    'maluje',
+    'tvaruje',
+    'spojuje',
+    'dělí',
+    'váže',
+    'zraňuje',
+    'chrání',
+    'bojuje',
+    'brání',
+    'útočí',
+    'uniká',
+    'lapá',
+    'osvobozuje',
+    'poutá',
+    'spřádá',
+    'tká',
+    'vrhá',
+    'nese',
+    'přenáší',
+    'vrací',
+    'zrychluje',
+    'zpomaluje',
+    'probouzí',
+    'uspává',
+    'šeptá',
+    'volá',
+    'hledí',
+    'čeká',
+    'bdí',
+    'rozkvétá',
+    'klíčí',
+    'zraje',
+    'chvěje',
+    'třpytí',
+    'shromažďuje',
+    'rozhazuje',
+    'tápe',
+    'žhne',
+    'vibruje',
+    'šumí',
+    'stéká',
+    'vypráví',
+    'plánuje',
+    'počítá',
+    'váhá',
+    'riskuje',
 ];
 /**
- * Extracts a deterministic numeric seed from a SHA-256 hash.
- */
-function getHashSeed(hash, segmentIndex) {
-    const expandedHash = `${hash}${hash}`;
-    const start = (segmentIndex * HASH_SEGMENT_LENGTH + segmentIndex) % hash.length;
-    return parseInt(expandedHash.substring(start, start + HASH_SEGMENT_LENGTH), 16);
-}
-/**
- * Picks a deterministic item from a list based on the hash seed.
- */
-function pickFromHash(hash, segmentIndex, list) {
-    const seed = getHashSeed(hash, segmentIndex);
-    return list[seed % list.length];
-}
-/**
- * Index constants for story part selection to avoid magic numbers.
- */
-const ADJECTIVE3_INDEX = 9;
-const NOUN3_INDEX = 10;
-/**
- * Creates the deterministic story parts used by the sentence templates.
+ * Czech word lists used by the linguistic hash.
+ *
+ * @private utility of `linguisticHash`
  */
-function createStoryParts(hash) {
-    return {
-        opener: pickFromHash(hash, 0, STORY_OPENERS),
-        connector: pickFromHash(hash, 1, STORY_CONNECTORS),
-        preposition: pickFromHash(hash, 2, STORY_PREPOSITIONS),
-        adjective1: pickFromHash(hash, 3, ADJECTIVES),
-        noun1: pickFromHash(hash, 4, NOUNS),
-        verb1: pickFromHash(hash, 5, VERBS),
-        adjective2: pickFromHash(hash, 6, ADJECTIVES),
-        noun2: pickFromHash(hash, 7, NOUNS),
-        verb2: pickFromHash(hash, 8, VERBS),
-        adjective3: pickFromHash(hash, ADJECTIVE3_INDEX, ADJECTIVES),
-        noun3: pickFromHash(hash, NOUN3_INDEX, NOUNS),
-    };
-}
+const LINGUISTIC_HASH_WORD_LISTS_CS = {
+    adjective: ADJECTIVES$1,
+    noun: NOUNS$1,
+    verb: VERBS$1,
+};
 /**
- * Index constant for story template selection to avoid magic numbers.
+ * Note: [💞] Ignore a discrepancy between file name and entity name
  */
-const STORY_TEMPLATE_INDEX = 11;
+
 /**
- * Builds a short, memorable story sentence from the hash.
+ * @@@
+ *
+ * @private utility of `linguisticHash`
  */
-function createStorySentence(hash) {
-    const parts = createStoryParts(hash);
-    const template = pickFromHash(hash, STORY_TEMPLATE_INDEX, STORY_TEMPLATES);
-    return template(parts).trim();
-}
 const ADJECTIVES = [
     'red',
     'blue',
@@ -7213,8 +7798,203 @@ const VERBS = [
     'spinning',
 ];
 /**
- * TODO: Prompt: Extract number constants and word list to a separate file for reuse.
+ * English word lists used by the linguistic hash.
+ *
+ * @private utility of `linguisticHash`
+ */
+const LINGUISTIC_HASH_WORD_LISTS_EN = {
+    adjective: ADJECTIVES,
+    noun: NOUNS,
+    verb: VERBS,
+};
+/**
+ * Note: [💞] Ignore a discrepancy between file name and entity name
+ */
+
+/**
+ * Default language used for linguistic hashes.
+ *
+ * @private utility of `linguisticHash`
+ */
+const DEFAULT_LINGUISTIC_HASH_LANGUAGE = 'en';
+/**
+ * @@@
+ *
+ * @private utility of `linguisticHash`
+ */
+const LANGUAGE_CONFIGS = {
+    en: {
+        language: 'en',
+        label: 'English',
+        wordLists: LINGUISTIC_HASH_WORD_LISTS_EN,
+    },
+    cs: {
+        language: 'cs',
+        label: 'Czech',
+        wordLists: LINGUISTIC_HASH_WORD_LISTS_CS,
+    },
+};
+/**
+ * Normalizes a requested language to a supported linguistic hash language.
+ *
+ * @private utility of `linguisticHash`
+ */
+function normalizeLinguisticHashLanguage(language) {
+    if (typeof language !== 'string') {
+        return DEFAULT_LINGUISTIC_HASH_LANGUAGE;
+    }
+    const normalized = language.trim().toLowerCase();
+    if (normalized === 'cs') {
+        return 'cs';
+    }
+    if (normalized === 'en') {
+        return 'en';
+    }
+    return DEFAULT_LINGUISTIC_HASH_LANGUAGE;
+}
+/**
+ * Returns the language configuration for linguistic hash generation.
+ *
+ * @private utility of `linguisticHash`
+ */
+function getLinguisticHashLanguageConfig(language) {
+    const normalized = normalizeLinguisticHashLanguage(language);
+    return LANGUAGE_CONFIGS[normalized];
+}
+
+// <- TODO: !!!! Remove re-exports
+/**
+ * Creates a human-readable hash as a short, story-like phrase.
+ *
+ * @param wordCount how many words to include (defaults to {@link DEFAULT_LINGUISTIC_HASH_WORD_COUNT}, clamped to
+ * {@link MIN_LINGUISTIC_HASH_WORD_COUNT}..{@link MAX_LINGUISTIC_HASH_WORD_COUNT})
+ * @param language optional language code (defaults to {@link DEFAULT_LINGUISTIC_HASH_LANGUAGE})
+ *
+ * @public exported from `@promptbook/utils`
+ */
+async function linguisticHash(input, wordCount, language) {
+    const hash = computeHash(input);
+    const normalizedWordCount = normalizeLinguisticHashWordCount(wordCount);
+    const languageConfig = getLinguisticHashLanguageConfig(language);
+    const words = createLinguisticHashWords(hash, normalizedWordCount, languageConfig.wordLists);
+    return capitalize(words.join(' '));
+}
+/**
+ * @@@
+ *
+ * @private utility of `linguisticHash`
+ */
+const HASH_SEGMENT_LENGTH = 8;
+/**
+ * The minimum number of words for a linguistic hash.
+ *
+ * @private utility of `linguisticHash`
+ */
+const MIN_LINGUISTIC_HASH_WORD_COUNT = 1;
+/**
+ * The default number of words for a linguistic hash.
+ *
+ * @private utility of `linguisticHash`
+ */
+const DEFAULT_LINGUISTIC_HASH_WORD_COUNT = 7;
+/**
+ * Extracts a deterministic numeric seed from a SHA-256 hash.
+ *
+ * @private utility of `linguisticHash`
+ */
+function getHashSeed(hash, segmentIndex) {
+    const expandedHash = `${hash}${hash}`;
+    const start = (segmentIndex * HASH_SEGMENT_LENGTH + segmentIndex) % hash.length;
+    return parseInt(expandedHash.substring(start, start + HASH_SEGMENT_LENGTH), 16);
+}
+/**
+ * Picks a deterministic item from a list based on the hash seed.
+ *
+ * @private utility of `linguisticHash`
+ */
+function pickFromHash(hash, segmentIndex, list) {
+    const seed = getHashSeed(hash, segmentIndex);
+    return list[seed % list.length];
+}
+/**
+ * Ordered word kinds used to build the linguistic hash output.
+ *
+ * @private utility of `linguisticHash`
+ */
+const WORD_SEQUENCE = [
+    'adjective',
+    'noun',
+    'verb',
+    'adjective',
+    'noun',
+    'verb',
+    'adjective',
+    'noun',
+    'verb',
+    'adjective',
+    'noun',
+    'verb',
+    'adjective',
+    'noun',
+    'verb',
+    'adjective',
+    'noun',
+    'verb',
+    'adjective',
+    'noun',
+];
+/**
+ * The maximum number of words for a linguistic hash.
+ *
+ * @private utility of `linguisticHash`
+ */
+const MAX_LINGUISTIC_HASH_WORD_COUNT = WORD_SEQUENCE.length;
+/**
+ * Index of the noun used for single-word hashes.
+ *
+ * @private utility of `linguisticHash`
+ */
+const SINGLE_WORD_INDEX = 1;
+/**
+ * Normalizes the word count to a supported integer range.
+ *
+ * @private utility of `linguisticHash`
+ */
+function normalizeLinguisticHashWordCount(wordCount) {
+    if (typeof wordCount !== 'number' || !Number.isFinite(wordCount)) {
+        return DEFAULT_LINGUISTIC_HASH_WORD_COUNT;
+    }
+    const rounded = Math.round(wordCount);
+    return Math.min(MAX_LINGUISTIC_HASH_WORD_COUNT, Math.max(MIN_LINGUISTIC_HASH_WORD_COUNT, rounded));
+}
+/**
+ * Picks a deterministic word from the hash by kind.
+ *
+ * @private utility of `linguisticHash`
+ */
+function pickWordFromHash(hash, segmentIndex, wordKind, wordLists) {
+    return pickFromHash(hash, segmentIndex, wordLists[wordKind]);
+}
+/**
+ * Creates the deterministic word sequence used for the linguistic hash output.
+ *
+ * @private utility of `linguisticHash`
+ */
+function createLinguisticHashWordSequence(hash, wordLists) {
+    return WORD_SEQUENCE.map((wordKind, index) => pickWordFromHash(hash, index, wordKind, wordLists));
+}
+/**
+ * Selects the requested number of words from the hash output.
+ *
+ * @private utility of `linguisticHash`
  */
+function createLinguisticHashWords(hash, wordCount, wordLists) {
+    const words = createLinguisticHashWordSequence(hash, wordLists);
+    if (wordCount === 1) {
+        return [words[SINGLE_WORD_INDEX]];
+    }
+    return words.slice(0, wordCount);
+}
 
 /**
  * Function parseNumber will parse number from string
@@ -9828,17 +10608,32 @@ class OpenAiAssistantExecutionTools extends OpenAiExecutionTools {
         });
     }
     async createNewAssistant(options) {
+        var _a, _b, _c;
         if (!this.isCreatingNewAssistantsAllowed) {
             throw new NotAllowed(`Creating new assistants is not allowed. Set \`isCreatingNewAssistantsAllowed: true\` in options to enable this feature.`);
         }
         // await this.playground();
         const { name, instructions, knowledgeSources, tools } = options;
+        const preparationStartedAtMs = Date.now();
+        const knowledgeSourcesCount = (_a = knowledgeSources === null || knowledgeSources === void 0 ? void 0 : knowledgeSources.length) !== null && _a !== void 0 ? _a : 0;
+        const toolsCount = (_b = tools === null || tools === void 0 ? void 0 : tools.length) !== null && _b !== void 0 ? _b : 0;
+        if (this.options.isVerbose) {
+            console.info('[🤰]', 'Starting OpenAI assistant creation', {
+                name,
+                knowledgeSourcesCount,
+                toolsCount,
+                instructionsLength: instructions.length,
+            });
+        }
         const client = await this.getClient();
         let vectorStoreId;
         // If knowledge sources are provided, create a vector store with them
         if (knowledgeSources && knowledgeSources.length > 0) {
             if (this.options.isVerbose) {
-                console.info(`📚 Creating vector store with ${knowledgeSources.length} knowledge sources...`);
+                console.info('[🤰]', 'Creating vector store with knowledge sources', {
+                    name,
+                    knowledgeSourcesCount,
+                });
             }
             // Create a vector store
             const vectorStore = await client.beta.vectorStores.create({
@@ -9846,12 +10641,22 @@ class OpenAiAssistantExecutionTools extends OpenAiExecutionTools {
             });
             vectorStoreId = vectorStore.id;
             if (this.options.isVerbose) {
-                console.info(`✅ Vector store created: ${vectorStoreId}`);
+                console.info('[🤰]', 'Vector store created', {
+                    vectorStoreId,
+                });
             }
             // Upload files from knowledge sources to the vector store
             const fileStreams = [];
-            for (const source of knowledgeSources) {
+            for (const [index, source] of knowledgeSources.entries()) {
                 try {
+                    if (this.options.isVerbose) {
+                        console.info('[🤰]', 'Processing knowledge source', {
+                            index: index + 1,
+                            total: knowledgeSources.length,
+                            source,
+                            sourceType: source.startsWith('http') || source.startsWith('https') ? 'url' : 'file',
+                        });
+                    }
                     // Check if it's a URL
                     if (source.startsWith('http://') || source.startsWith('https://')) {
                         // Download the file
@@ -9896,7 +10701,10 @@ class OpenAiAssistantExecutionTools extends OpenAiExecutionTools {
                         files: fileStreams,
                     });
                     if (this.options.isVerbose) {
-                        console.info(`✅ Uploaded ${fileStreams.length} files to vector store`);
+                        console.info('[🤰]', 'Uploaded files to vector store', {
+                            vectorStoreId,
+                            fileCount: fileStreams.length,
+                        });
                     }
                 }
                 catch (error) {
@@ -9924,8 +10732,21 @@ class OpenAiAssistantExecutionTools extends OpenAiExecutionTools {
                 },
             };
         }
+        if (this.options.isVerbose) {
+            console.info('[🤰]', 'Creating OpenAI assistant', {
+                name,
+                model: assistantConfig.model,
+                toolCount: (_c = assistantConfig === null || assistantConfig === void 0 ? void 0 : assistantConfig.tools) === null || _c === void 0 ? void 0 : _c.length,
+                hasVectorStore: Boolean(vectorStoreId),
+            });
+        }
         const assistant = await client.beta.assistants.create(assistantConfig);
-        console.log(`✅ Assistant created: ${assistant.id}`);
+        if (this.options.isVerbose) {
+            console.info('[🤰]', 'OpenAI assistant created', {
+                assistantId: assistant.id,
+                elapsedMs: Date.now() - preparationStartedAtMs,
+            });
+        }
         // TODO: [🐱‍🚀] Try listing existing assistants
         // TODO: [🐱‍🚀] Try marking existing assistants by DISCRIMINANT
         // TODO: [🐱‍🚀] Allow to update and reconnect to existing assistants
@@ -9936,17 +10757,34 @@ class OpenAiAssistantExecutionTools extends OpenAiExecutionTools {
         });
     }
     async updateAssistant(options) {
+        var _a, _b, _c, _d;
         if (!this.isCreatingNewAssistantsAllowed) {
             throw new NotAllowed(`Updating assistants is not allowed. Set \`isCreatingNewAssistantsAllowed: true\` in options to enable this feature.`);
         }
         const { assistantId, name, instructions, knowledgeSources, tools } = options;
+        const preparationStartedAtMs = Date.now();
+        const knowledgeSourcesCount = (_a = knowledgeSources === null || knowledgeSources === void 0 ? void 0 : knowledgeSources.length) !== null && _a !== void 0 ? _a : 0;
+        const toolsCount = (_b = tools === null || tools === void 0 ? void 0 : tools.length) !== null && _b !== void 0 ? _b : 0;
+        if (this.options.isVerbose) {
+            console.info('[🤰]', 'Starting OpenAI assistant update', {
+                assistantId,
+                name,
+                knowledgeSourcesCount,
+                toolsCount,
+                instructionsLength: (_c = instructions === null || instructions === void 0 ? void 0 : instructions.length) !== null && _c !== void 0 ? _c : 0,
+            });
+        }
         const client = await this.getClient();
         let vectorStoreId;
         // If knowledge sources are provided, create a vector store with them
         // TODO: [🧠] Reuse vector store creation logic from createNewAssistant
         if (knowledgeSources && knowledgeSources.length > 0) {
             if (this.options.isVerbose) {
-                console.info(`📚 Creating vector store for update with ${knowledgeSources.length} knowledge sources...`);
+                console.info('[🤰]', 'Creating vector store for assistant update', {
+                    assistantId,
+                    name,
+                    knowledgeSourcesCount,
+                });
             }
             // Create a vector store
             const vectorStore = await client.beta.vectorStores.create({
@@ -9954,12 +10792,22 @@ class OpenAiAssistantExecutionTools extends OpenAiExecutionTools {
             });
             vectorStoreId = vectorStore.id;
             if (this.options.isVerbose) {
-                console.info(`✅ Vector store created: ${vectorStoreId}`);
+                console.info('[🤰]', 'Vector store created for assistant update', {
+                    vectorStoreId,
+                });
             }
             // Upload files from knowledge sources to the vector store
             const fileStreams = [];
-            for (const source of knowledgeSources) {
+            for (const [index, source] of knowledgeSources.entries()) {
                 try {
+                    if (this.options.isVerbose) {
+                        console.info('[🤰]', 'Processing knowledge source for update', {
+                            index: index + 1,
+                            total: knowledgeSources.length,
+                            source,
+                            sourceType: source.startsWith('http') || source.startsWith('https') ? 'url' : 'file',
+                        });
+                    }
                     // Check if it's a URL
                     if (source.startsWith('http://') || source.startsWith('https://')) {
                         // Download the file
@@ -10004,7 +10852,10 @@ class OpenAiAssistantExecutionTools extends OpenAiExecutionTools {
                         files: fileStreams,
                     });
                     if (this.options.isVerbose) {
-                        console.info(`✅ Uploaded ${fileStreams.length} files to vector store`);
+                        console.info('[🤰]', 'Uploaded files to vector store for update', {
+                            vectorStoreId,
+                            fileCount: fileStreams.length,
+                        });
                     }
                 }
                 catch (error) {
@@ -10028,9 +10879,20 @@ class OpenAiAssistantExecutionTools extends OpenAiExecutionTools {
                 },
             };
         }
+        if (this.options.isVerbose) {
+            console.info('[🤰]', 'Updating OpenAI assistant', {
+                assistantId,
+                name,
+                toolCount: (_d = assistantUpdate === null || assistantUpdate === void 0 ? void 0 : assistantUpdate.tools) === null || _d === void 0 ? void 0 : _d.length,
+                hasVectorStore: Boolean(vectorStoreId),
+            });
+        }
         const assistant = await client.beta.assistants.update(assistantId, assistantUpdate);
         if (this.options.isVerbose) {
-            console.log(`✅ Assistant updated: ${assistant.id}`);
+            console.info('[🤰]', 'OpenAI assistant updated', {
+                assistantId: assistant.id,
+                elapsedMs: Date.now() - preparationStartedAtMs,
+            });
         }
         return new OpenAiAssistantExecutionTools({
             ...this.options,
@@ -27818,6 +28680,21 @@ function book(strings, ...values) {
  * Note: [💞] Ignore a discrepancy between file name and entity name
  */
 
+/**
+ * Tool call name emitted while preparing a GPT assistant for an agent.
+ *
+ * @public exported from `@promptbook/types`
+ */
+const ASSISTANT_PREPARATION_TOOL_CALL_NAME = 'assistant_preparation';
+/**
+ * Checks whether a tool call is the assistant preparation marker.
+ *
+ * @public exported from `@promptbook/types`
+ */
+function isAssistantPreparationToolCall(toolCall) {
+    return toolCall.name === ASSISTANT_PREPARATION_TOOL_CALL_NAME;
+}
+
 /*! *****************************************************************************
 Copyright (c) Microsoft Corporation.
 
@@ -27930,14 +28807,27 @@ function humanizeAiTextEmdashed(aiText) {
  * @public exported from `@promptbook/markdown-utils`
  */
 function humanizeAiTextQuotes(aiText) {
-    return aiText
-        .replace(/[“”„‟«»❝❞〝〞〟＂]/g, '"')
-        .replace(/[‚‘’‛‹›❛❜＇ʼ]/g, "'");
+    return aiText.replace(/[“”„‟«»❝❞〝〞〟＂]/g, '"').replace(/[‚‘’‛‹›❛❜＇ʼ]/g, "'");
 }
 /**
  * Note: [🏂] This function is not tested by itself but together with other cleanup functions with `humanizeAiText`
  */
 
+/**
+ * Remove bracketed source citation artifacts like `\u30105:1\u2020source\u3011`.
+ *
+ * Note: [??] This function is idempotent.
+ * Tip: If you want to do the full cleanup, look for `humanizeAiText` exported `@promptbook/markdown-utils`
+ *
+ * @public exported from `@promptbook/markdown-utils`
+ */
+function humanizeAiTextSources(aiText) {
+    return aiText.replace(/[ \t]*\u3010\s*\d+(?:\s*:\s*\d+)?\s*\u2020source\s*\u3011/g, '');
+}
+/**
+ * Note: [??] This function is not tested by itself but together with other cleanup functions with `humanizeAiText`
+ */
+
 /**
  * Change unprintable hard spaces to regular spaces and drop zero-width spaces
  *
@@ -27947,9 +28837,7 @@ function humanizeAiTextQuotes(aiText) {
  * @public exported from `@promptbook/markdown-utils`
  */
 function humanizeAiTextWhitespace(aiText) {
-    return aiText
-        .replace(/[\u00A0\u1680\u2000-\u200A\u202F\u205F\u3000]/g, ' ')
-        .replace(/[\u200B\uFEFF\u2060]/g, '');
+    return aiText.replace(/[\u00A0\u1680\u2000-\u200A\u202F\u205F\u3000]/g, ' ').replace(/[\u200B\uFEFF\u2060]/g, '');
 }
 /**
  * Note: [🏂] This function is not tested by itself but together with other cleanup functions with `humanizeAiText`
@@ -27968,6 +28856,7 @@ function humanizeAiText(aiText) {
     cleanedText = humanizeAiTextEllipsis(cleanedText);
     cleanedText = humanizeAiTextEmdashed(cleanedText);
     cleanedText = humanizeAiTextQuotes(cleanedText);
+    cleanedText = humanizeAiTextSources(cleanedText);
     cleanedText = humanizeAiTextWhitespace(cleanedText);
     return cleanedText;
 }
@@ -28228,6 +29117,33 @@ class OpenAiAgentExecutionTools extends OpenAiExecutionTools {
     }
 }
 
+/**
+ * Emits a progress update to signal assistant preparation before long setup work.
+ */
+function emitAssistantPreparationProgress(options) {
+    const startedAt = $getCurrentDate();
+    options.onProgress({
+        content: '',
+        modelName: options.modelName,
+        timing: {
+            start: startedAt,
+            complete: startedAt,
+        },
+        usage: UNCERTAIN_USAGE,
+        rawPromptContent: options.prompt.content,
+        rawRequest: null,
+        rawResponse: {
+            status: 'assistant_preparation',
+        },
+        toolCalls: [
+            {
+                name: ASSISTANT_PREPARATION_TOOL_CALL_NAME,
+                arguments: options.phase ? { phase: options.phase } : {},
+                createdAt: startedAt,
+            },
+        ],
+    });
+}
 /**
  * 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
@@ -28286,10 +29202,32 @@ class AgentLlmExecutionTools {
      */
     async getModelRequirements() {
         if (this._cachedModelRequirements === null) {
+            const preparationStartedAtMs = Date.now();
+            if (this.options.isVerbose) {
+                console.info('[🤰]', 'Preparing agent model requirements', {
+                    agent: this.title,
+                });
+            }
             // Get available models from underlying LLM tools for best model selection
+            const availableModelsStartedAtMs = Date.now();
             const availableModels = await this.options.llmTools.listModels();
+            if (this.options.isVerbose) {
+                console.info('[🤰]', 'Available models resolved for agent', {
+                    agent: this.title,
+                    modelCount: availableModels.length,
+                    elapsedMs: Date.now() - availableModelsStartedAtMs,
+                });
+            }
+            const requirementsStartedAtMs = Date.now();
             this._cachedModelRequirements = await createAgentModelRequirements(this.options.agentSource, undefined, // Let the function pick the best model
             availableModels);
+            if (this.options.isVerbose) {
+                console.info('[🤰]', 'Agent model requirements ready', {
+                    agent: this.title,
+                    elapsedMs: Date.now() - requirementsStartedAtMs,
+                    totalElapsedMs: Date.now() - preparationStartedAtMs,
+                });
+            }
         }
         return this._cachedModelRequirements;
     }
@@ -28443,14 +29381,26 @@ class AgentLlmExecutionTools {
             if (cached) {
                 if (cached.requirementsHash === requirementsHash) {
                     if (this.options.isVerbose) {
-                        console.log(`1️⃣ Using cached OpenAI Assistant for agent ${this.title}...`);
+                        console.info('[🤰]', 'Using cached OpenAI Assistant', {
+                            agent: this.title,
+                            assistantId: cached.assistantId,
+                        });
                     }
                     assistant = this.options.llmTools.getAssistant(cached.assistantId);
                 }
                 else {
                     if (this.options.isVerbose) {
-                        console.log(`1️⃣ Updating OpenAI Assistant for agent ${this.title}...`);
+                        console.info('[🤰]', 'Updating OpenAI Assistant', {
+                            agent: this.title,
+                            assistantId: cached.assistantId,
+                        });
                     }
+                    emitAssistantPreparationProgress({
+                        onProgress,
+                        prompt,
+                        modelName: this.modelName,
+                        phase: 'Updating assistant',
+                    });
                     assistant = await this.options.llmTools.updateAssistant({
                         assistantId: cached.assistantId,
                         name: this.title,
@@ -28466,9 +29416,17 @@ class AgentLlmExecutionTools {
             }
             else {
                 if (this.options.isVerbose) {
-                    console.log(`1️⃣ Creating new OpenAI Assistant for agent ${this.title}...`);
+                    console.info('[🤰]', 'Creating new OpenAI Assistant', {
+                        agent: this.title,
+                    });
                 }
                 // <- TODO: [🐱‍🚀] Check also `isCreatingNewAssistantsAllowed` and warn about it
+                emitAssistantPreparationProgress({
+                    onProgress,
+                    prompt,
+                    modelName: this.modelName,
+                    phase: 'Creating assistant',
+                });
                 assistant = await this.options.llmTools.createNewAssistant({
                     name: this.title,
                     instructions: modelRequirements.systemMessage,
@@ -28541,6 +29499,58 @@ AgentLlmExecutionTools.vectorStoreCache = new Map();
  */
 
 var _Agent_instances, _Agent_selfLearnNonce, _Agent_selfLearnSamples, _Agent_selfLearnTeacher;
+/**
+ * Creates an empty commitment breakdown for self-learning summaries.
+ */
+function createEmptySelfLearningCommitmentCounts() {
+    return {
+        total: 0,
+        knowledge: 0,
+        rule: 0,
+        persona: 0,
+        other: 0,
+    };
+}
+/**
+ * Summarizes teacher commitments into user-friendly counts for self-learning.
+ */
+function summarizeTeacherCommitments(commitments) {
+    var _a, _b;
+    const counts = createEmptySelfLearningCommitmentCounts();
+    const lines = commitments
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0 && line !== '---' && !line.startsWith('```'));
+    for (const line of lines) {
+        const keyword = (_b = (_a = line.split(/\s+/)[0]) === null || _a === void 0 ? void 0 : _a.toUpperCase()) !== null && _b !== void 0 ? _b : '';
+        if (!/^[A-Z][A-Z_-]*$/.test(keyword)) {
+            continue;
+        }
+        counts.total += 1;
+        if (keyword === 'KNOWLEDGE') {
+            counts.knowledge += 1;
+        }
+        else if (keyword === 'RULE') {
+            counts.rule += 1;
+        }
+        else if (keyword === 'PERSONA') {
+            counts.persona += 1;
+        }
+        else {
+            counts.other += 1;
+        }
+    }
+    return counts;
+}
+/**
+ * Builds the teacher summary payload for the self-learning tool call.
+ */
+function buildTeacherSummary(commitments, used) {
+    return {
+        used,
+        commitmentTypes: summarizeTeacherCommitments(commitments),
+    };
+}
 /**
  * Represents one AI Agent
  *
@@ -28715,16 +29725,29 @@ class Agent extends AgentLlmExecutionTools {
         // 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
-        await __classPrivateFieldGet(this, _Agent_instances, "m", _Agent_selfLearnTeacher).call(this, prompt, result).catch((error) => {
+        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;
+        }
         // Note: [4] Notify end of self-learning
+        const completedAt = new Date().toISOString();
+        const selfLearningResult = {
+            success: true,
+            startedAt: selfLearningToolCall.createdAt,
+            completedAt,
+            samplesAdded: 1,
+            teacher: teacherSummary || undefined,
+        };
         const completedSelfLearningToolCall = {
             ...selfLearningToolCall,
-            result: { success: true },
+            result: selfLearningResult,
         };
         const finalResult = {
             ...result,
@@ -28773,7 +29796,7 @@ async function _Agent_selfLearnNonce() {
 async function _Agent_selfLearnTeacher(prompt, result) {
     // [1] Call the teacher agent // <- !!!!! Emojis
     if (this.teacherAgent === null) {
-        return;
+        return null;
     }
     console.info(colors.bgCyan('[Self-learning]') + colors.cyan(' Teacher'));
     const teacherResult = await this.teacherAgent.callChatModel({
@@ -28828,7 +29851,7 @@ async function _Agent_selfLearnTeacher(prompt, result) {
     if (teacherCommitments === '') {
         console.info(colors.bgCyan('[Self-learning]') +
             colors.cyan(' Teacher agent did not provide new commitments to learn'));
-        return;
+        return buildTeacherSummary('', true);
     }
     // [2] Append to the current source
     const currentSource = this.agentSource.value;
@@ -28836,6 +29859,7 @@ async function _Agent_selfLearnTeacher(prompt, result) {
     // <- 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?
@@ -28999,6 +30023,8 @@ class RemoteAgent extends Agent {
         // <- TODO: [🐱‍🚀] Maybe use promptbookFetch
         let content = '';
         const toolCalls = [];
+        const preparationToolCalls = [];
+        let hasReceivedModelOutput = false;
         const normalizeToolCall = (toolCall) => {
             if (toolCall.createdAt) {
                 return toolCall;
@@ -29045,6 +30071,17 @@ class RemoteAgent extends Agent {
         const upsertToolCalls = (incomingToolCalls) => {
             for (const toolCall of incomingToolCalls) {
                 const normalized = normalizeToolCall(toolCall);
+                if (isAssistantPreparationToolCall(normalized)) {
+                    if (hasReceivedModelOutput) {
+                        continue;
+                    }
+                    preparationToolCalls.length = 0;
+                    preparationToolCalls.push(normalized);
+                    continue;
+                }
+                if (preparationToolCalls.length > 0) {
+                    preparationToolCalls.length = 0;
+                }
                 const key = getToolCallKey(normalized);
                 const existingIndex = toolCalls.findIndex((existing) => getToolCallKey(existing) === key);
                 if (existingIndex === -1) {
@@ -29055,6 +30092,10 @@ class RemoteAgent extends Agent {
                 }
             }
         };
+        /**
+         * Builds the tool call list including any preparation marker still active.
+         */
+        const getActiveToolCalls = () => preparationToolCalls.length > 0 ? [...preparationToolCalls, ...toolCalls] : toolCalls;
         if (!bookResponse.body) {
             content = await bookResponse.text();
         }
@@ -29091,7 +30132,7 @@ class RemoteAgent extends Agent {
                                             rawPromptContent: {},
                                             rawRequest: {},
                                             rawResponse: {},
-                                            toolCalls: normalizedToolCalls,
+                                            toolCalls: getActiveToolCalls(),
                                         });
                                         sawToolCalls = true;
                                         isToolCallLine = true;
@@ -29119,6 +30160,10 @@ class RemoteAgent extends Agent {
                             // console.debug('RemoteAgent chunk:', textChunk);
                             content += textChunk;
                         }
+                        if (!hasReceivedModelOutput && content.trim().length > 0) {
+                            hasReceivedModelOutput = true;
+                            preparationToolCalls.length = 0;
+                        }
                         onProgress({
                             content,
                             modelName: this.modelName,
@@ -29127,7 +30172,7 @@ class RemoteAgent extends Agent {
                             rawPromptContent: {},
                             rawRequest: {},
                             rawResponse: {},
-                            toolCalls,
+                            toolCalls: getActiveToolCalls(),
                         });
                     }
                 }
@@ -29135,6 +30180,10 @@ class RemoteAgent extends Agent {
                 const lastChunk = decoder.decode();
                 if (lastChunk) {
                     content += lastChunk;
+                    if (!hasReceivedModelOutput && content.trim().length > 0) {
+                        hasReceivedModelOutput = true;
+                        preparationToolCalls.length = 0;
+                    }
                     onProgress({
                         content: lastChunk,
                         modelName: this.modelName,
@@ -29143,7 +30192,7 @@ class RemoteAgent extends Agent {
                         rawPromptContent: {},
                         rawRequest: {},
                         rawResponse: {},
-                        toolCalls,
+                        toolCalls: getActiveToolCalls(),
                     });
                 }
             }