@promptbook/core 0.104.0-1 → 0.104.0-11

package/umd/index.umd.js

@@ -28,7 +28,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.104.0-1';
+    const PROMPTBOOK_ENGINE_VERSION = '0.104.0-11';
     /**
      * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
      * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -38,6 +38,8 @@
      * Core Promptbook server configuration.
      *
      * This server is also used for auto-federation in the Agents Server.
+     *
+     * @public exported from `@promptbook/core`
      */
     const CORE_SERVER = {
         title: 'Promptbook Core',
@@ -3745,6 +3747,15 @@
                 return promptResult;
             };
         }
+        if (llmTools.callImageGenerationModel !== undefined) {
+            proxyTools.callImageGenerationModel = async (prompt) => {
+                // console.info('[🚕] callImageGenerationModel through countTotalUsage');
+                const promptResult = await llmTools.callImageGenerationModel(prompt);
+                totalUsage = addUsage(totalUsage, promptResult.usage);
+                spending.next(promptResult.usage);
+                return promptResult;
+            };
+        }
         // <- Note: [🤖]
         return proxyTools;
     }
@@ -3753,7 +3764,7 @@
      * TODO: [🧠] Is there some meaningfull way how to test this util
      * TODO: [🧠][🌯] Maybe a way how to hide ability to `get totalUsage`
      *     > const [llmToolsWithUsage,getUsage] = countTotalUsage(llmTools);
-     * TODO: [👷‍♂️] @@@ Manual about construction of llmTools
+     * TODO: [👷‍♂️] Write a comprehensive manual explaining the construction and usage of LLM tools in the Promptbook ecosystem
      */
 
     /**
@@ -3854,6 +3865,12 @@
         callEmbeddingModel(prompt) {
             return this.callCommonModel(prompt);
         }
+        /**
+         * Calls the best available embedding model
+         */
+        callImageGenerationModel(prompt) {
+            return this.callCommonModel(prompt);
+        }
         // <- Note: [🤖]
         /**
          * Calls the best available model
@@ -3880,6 +3897,11 @@
                                 continue llm;
                             }
                             return await llmExecutionTools.callEmbeddingModel(prompt);
+                        case 'IMAGE_GENERATION':
+                            if (llmExecutionTools.callImageGenerationModel === undefined) {
+                                continue llm;
+                            }
+                            return await llmExecutionTools.callImageGenerationModel(prompt);
                         // <- case [🤖]:
                         default:
                             throw new UnexpectedError(`Unknown model variant "${prompt.modelRequirements.modelVariant}" in ${llmExecutionTools.title}`);
@@ -6305,8 +6327,9 @@
                                         $ongoingTaskResult.$resultString = $ongoingTaskResult.$completionResult.content;
                                         break variant;
                                     case 'EMBEDDING':
+                                    case 'IMAGE_GENERATION':
                                         throw new PipelineExecutionError(spaceTrim$1.spaceTrim((block) => `
-                                                Embedding model can not be used in pipeline
+                                                ${modelRequirements.modelVariant} model can not be used in pipeline
 
                                                 This should be catched during parsing
 
@@ -7965,6 +7988,114 @@
      * Note: [💞] Ignore a discrepancy between file name and entity name
      */
 
+    /**
+     * DICTIONARY commitment definition
+     *
+     * The DICTIONARY commitment defines specific terms and their meanings that the agent should use correctly
+     * in its reasoning and responses. This ensures consistent terminology usage.
+     *
+     * Key features:
+     * - Multiple DICTIONARY commitments are automatically merged into one
+     * - Content is placed in a dedicated section of the system message
+     * - Terms and definitions are stored in metadata.DICTIONARY for debugging
+     * - Agent should use the defined terms correctly in responses
+     *
+     * Example usage in agent source:
+     *
+     * ```book
+     * Legal Assistant
+     *
+     * PERSONA You are a knowledgeable legal assistant
+     * DICTIONARY Misdemeanor is a minor wrongdoing or criminal offense
+     * DICTIONARY Felony is a serious crime usually punishable by imprisonment for more than one year
+     * DICTIONARY Tort is a civil wrong that causes harm or loss to another person, leading to legal liability
+     * ```
+     *
+     * @private [🪔] Maybe export the commitments through some package
+     */
+    class DictionaryCommitmentDefinition extends BaseCommitmentDefinition {
+        constructor() {
+            super('DICTIONARY');
+        }
+        /**
+         * Short one-line description of DICTIONARY.
+         */
+        get description() {
+            return 'Define terms and their meanings for consistent terminology usage.';
+        }
+        /**
+         * Icon for this commitment.
+         */
+        get icon() {
+            return '📚';
+        }
+        /**
+         * Markdown documentation for DICTIONARY commitment.
+         */
+        get documentation() {
+            return spaceTrim$1.spaceTrim(`
+            # DICTIONARY
+
+            Defines specific terms and their meanings that the agent should use correctly in reasoning and responses.
+
+            ## Key aspects
+
+            - Multiple \`DICTIONARY\` commitments are merged together.
+            - Terms are defined in the format: "Term is definition"
+            - The agent should use these terms consistently in responses.
+            - Definitions help ensure accurate and consistent terminology.
+
+            ## Examples
+
+            \`\`\`book
+            Legal Assistant
+
+            PERSONA You are a knowledgeable legal assistant specializing in criminal law
+            DICTIONARY Misdemeanor is a minor wrongdoing or criminal offense
+            DICTIONARY Felony is a serious crime usually punishable by imprisonment for more than one year
+            DICTIONARY Tort is a civil wrong that causes harm or loss to another person, leading to legal liability
+            \`\`\`
+
+            \`\`\`book
+            Medical Assistant
+
+            PERSONA You are a helpful medical assistant
+            DICTIONARY Hypertension is persistently high blood pressure
+            DICTIONARY Diabetes is a chronic condition that affects how the body processes blood sugar
+            DICTIONARY Vaccine is a biological preparation that provides active immunity to a particular disease
+            \`\`\`
+        `);
+        }
+        applyToAgentModelRequirements(requirements, content) {
+            var _a;
+            const trimmedContent = content.trim();
+            if (!trimmedContent) {
+                return requirements;
+            }
+            // Get existing dictionary entries from metadata
+            const existingDictionary = ((_a = requirements.metadata) === null || _a === void 0 ? void 0 : _a.DICTIONARY) || '';
+            // Merge the new dictionary entry with existing entries
+            const mergedDictionary = existingDictionary
+                ? `${existingDictionary}\n${trimmedContent}`
+                : trimmedContent;
+            // Store the merged dictionary in metadata for debugging and inspection
+            const updatedMetadata = {
+                ...requirements.metadata,
+                DICTIONARY: mergedDictionary,
+            };
+            // Create the dictionary section for the system message
+            // Format: "# DICTIONARY\nTerm: definition\nTerm: definition..."
+            const dictionarySection = `# DICTIONARY\n${mergedDictionary}`;
+            return {
+                ...this.appendToSystemMessage(requirements, dictionarySection),
+                metadata: updatedMetadata,
+            };
+        }
+    }
+    /**
+     * Note: [💞] Ignore a discrepancy between file name and entity name
+     */
+
     /**
      * FORMAT commitment definition
      *
@@ -10785,6 +10916,7 @@
         new DeleteCommitmentDefinition('CANCEL'),
         new DeleteCommitmentDefinition('DISCARD'),
         new DeleteCommitmentDefinition('REMOVE'),
+        new DictionaryCommitmentDefinition(),
         new OpenCommitmentDefinition(),
         new ClosedCommitmentDefinition(),
         new UseBrowserCommitmentDefinition(),
@@ -10936,17 +11068,64 @@
             };
         }
         const lines = agentSource.split('\n');
-        const agentName = (((_a = lines[0]) === null || _a === void 0 ? void 0 : _a.trim()) || null);
+        let agentName = null;
+        let agentNameLineIndex = -1;
+        // Find the agent name: first non-empty line that is not a commitment and not a horizontal line
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            if (line === undefined) {
+                continue;
+            }
+            const trimmed = line.trim();
+            if (!trimmed) {
+                continue;
+            }
+            const isHorizontal = HORIZONTAL_LINE_PATTERN.test(line);
+            if (isHorizontal) {
+                continue;
+            }
+            let isCommitment = false;
+            for (const definition of COMMITMENT_REGISTRY) {
+                const typeRegex = definition.createTypeRegex();
+                const match = typeRegex.exec(trimmed);
+                if (match && ((_a = match.groups) === null || _a === void 0 ? void 0 : _a.type)) {
+                    isCommitment = true;
+                    break;
+                }
+            }
+            if (!isCommitment) {
+                agentName = trimmed;
+                agentNameLineIndex = i;
+                break;
+            }
+        }
         const commitments = [];
         const nonCommitmentLines = [];
-        // Always add the first line (agent name) to non-commitment lines
-        if (lines[0] !== undefined) {
-            nonCommitmentLines.push(lines[0]);
+        // Add lines before agentName that are horizontal lines (they are non-commitment)
+        for (let i = 0; i < agentNameLineIndex; i++) {
+            const line = lines[i];
+            if (line === undefined) {
+                continue;
+            }
+            const trimmed = line.trim();
+            if (!trimmed) {
+                continue;
+            }
+            const isHorizontal = HORIZONTAL_LINE_PATTERN.test(line);
+            if (isHorizontal) {
+                nonCommitmentLines.push(line);
+            }
+            // Note: Commitments before agentName are not added to nonCommitmentLines
+        }
+        // Add the agent name line to non-commitment lines
+        if (agentNameLineIndex >= 0) {
+            nonCommitmentLines.push(lines[agentNameLineIndex]);
         }
         // Parse commitments with multiline support
         let currentCommitment = null;
-        // Process lines starting from the second line (skip agent name)
-        for (let i = 1; i < lines.length; i++) {
+        // Process lines starting from after the agent name line
+        const startIndex = agentNameLineIndex >= 0 ? agentNameLineIndex + 1 : 0;
+        for (let i = startIndex; i < lines.length; i++) {
             const line = lines[i];
             if (line === undefined) {
                 continue;
@@ -11166,7 +11345,12 @@
             };
         }
         // Apply each commitment in order using reduce-like pattern
-        for (const commitment of filteredCommitments) {
+        for (let i = 0; i < filteredCommitments.length; i++) {
+            const commitment = filteredCommitments[i];
+            // CLOSED commitment should work only if its the last commitment in the book
+            if (commitment.type === 'CLOSED' && i !== filteredCommitments.length - 1) {
+                continue;
+            }
             const definition = getCommitmentDefinition(commitment.type);
             if (definition) {
                 try {
@@ -11261,44 +11445,6 @@
      * TODO: [🌺] Use some intermediate util splitWords
      */
 
-    /**
-     * Generates a gravatar URL based on agent name for fallback avatar
-     *
-     * @param agentName The agent name to generate avatar for
-     * @returns Gravatar URL
-     *
-     * @private - [🤹] The fact that profile image is Gravatar is just implementation detail which should be hidden for consumer
-     */
-    function generateGravatarUrl(agentName) {
-        // Use a default name if none provided
-        const safeName = agentName || 'Anonymous Agent';
-        // Create a simple hash from the name for consistent avatar
-        let hash = 0;
-        for (let i = 0; i < safeName.length; i++) {
-            const char = safeName.charCodeAt(i);
-            hash = (hash << 5) - hash + char;
-            hash = hash & hash; // Convert to 32bit integer
-        }
-        const avatarId = Math.abs(hash).toString();
-        return `https://www.gravatar.com/avatar/${avatarId}?default=robohash&size=200&rating=x`;
-    }
-
-    /**
-     * Generates an image for the agent to use as profile image
-     *
-     * @param agentName The agent name to generate avatar for
-     * @returns The placeholder profile image URL for the agent
-     *
-     * @public exported from `@promptbook/core`
-     */
-    function generatePlaceholderAgentProfileImageUrl(agentName) {
-        // Note: [🤹] The fact that profile image is Gravatar is just implementation detail which should be hidden for consumer
-        return generateGravatarUrl(agentName);
-    }
-    /**
-     * TODO: [🤹] Figure out best placeholder image generator https://i.pravatar.cc/1000?u=568
-     */
-
     /**
      * Creates a Mermaid graph based on the promptbook
      *
@@ -11469,13 +11615,14 @@
      *
      * @public exported from `@promptbook/utils`
      */
-    const $isRunningInBrowser = new Function(`
-    try {
-        return this === window;
-    } catch (e) {
-        return false;
+    function $isRunningInBrowser() {
+        try {
+            return typeof window !== 'undefined' && typeof window.document !== 'undefined';
+        }
+        catch (e) {
+            return false;
+        }
     }
-`);
     /**
      * TODO: [🎺]
      */
@@ -11487,13 +11634,15 @@
      *
      * @public exported from `@promptbook/utils`
      */
-    const $isRunningInJest = new Function(`
-    try {
-        return process.env.JEST_WORKER_ID !== undefined;
-    } catch (e) {
-        return false;
+    function $isRunningInJest() {
+        var _a;
+        try {
+            return typeof process !== 'undefined' && ((_a = process.env) === null || _a === void 0 ? void 0 : _a.JEST_WORKER_ID) !== undefined;
+        }
+        catch (e) {
+            return false;
+        }
     }
-`);
     /**
      * TODO: [🎺]
      */
@@ -11505,13 +11654,14 @@
      *
      * @public exported from `@promptbook/utils`
      */
-    const $isRunningInNode = new Function(`
-    try {
-        return this === global;
-    } catch (e) {
-        return false;
+    function $isRunningInNode() {
+        try {
+            return typeof process !== 'undefined' && process.versions != null && process.versions.node != null;
+        }
+        catch (e) {
+            return false;
+        }
     }
-`);
     /**
      * TODO: [🎺]
      */
@@ -11523,17 +11673,17 @@
      *
      * @public exported from `@promptbook/utils`
      */
-    const $isRunningInWebWorker = new Function(`
-    try {
-        if (typeof WorkerGlobalScope !== 'undefined' && self instanceof WorkerGlobalScope) {
-            return true;
-        } else {
+    function $isRunningInWebWorker() {
+        try {
+            // Note: Check for importScripts which is specific to workers
+            //       and not available in the main browser thread
+            return (typeof self !== 'undefined' &&
+                typeof self.importScripts === 'function');
+        }
+        catch (e) {
             return false;
         }
-    } catch (e) {
-        return false;
     }
-`);
     /**
      * TODO: [🎺]
      */
@@ -11746,7 +11896,57 @@
         }
         const meta = {};
         const links = [];
+        const capabilities = [];
         for (const commitment of parseResult.commitments) {
+            if (commitment.type === 'USE BROWSER') {
+                capabilities.push({
+                    type: 'browser',
+                    label: 'Browser',
+                    iconName: 'Globe',
+                });
+                continue;
+            }
+            if (commitment.type === 'USE SEARCH ENGINE') {
+                capabilities.push({
+                    type: 'search-engine',
+                    label: 'Search Internet',
+                    iconName: 'Search',
+                });
+                continue;
+            }
+            if (commitment.type === 'KNOWLEDGE') {
+                const content = spaceTrim__default["default"](commitment.content).split('\n')[0] || '';
+                let label = content;
+                let iconName = 'Book';
+                if (content.startsWith('http://') || content.startsWith('https://')) {
+                    try {
+                        const url = new URL(content);
+                        if (url.pathname.endsWith('.pdf')) {
+                            label = url.pathname.split('/').pop() || 'Document.pdf';
+                            iconName = 'FileText';
+                        }
+                        else {
+                            label = url.hostname.replace(/^www\./, '');
+                        }
+                    }
+                    catch (e) {
+                        // Invalid URL, treat as text
+                    }
+                }
+                else {
+                    // Text content - take first few words
+                    const words = content.split(/\s+/);
+                    if (words.length > 4) {
+                        label = words.slice(0, 4).join(' ') + '...';
+                    }
+                }
+                capabilities.push({
+                    type: 'knowledge',
+                    label,
+                    iconName,
+                });
+                continue;
+            }
             if (commitment.type === 'META LINK') {
                 const linkValue = spaceTrim__default["default"](commitment.content);
                 links.push(linkValue);
@@ -11776,10 +11976,6 @@
             const metaType = normalizeTo_camelCase(metaTypeRaw);
             meta[metaType] = spaceTrim__default["default"](commitment.content.substring(metaTypeRaw.length));
         }
-        // Generate gravatar fallback if no meta image specified
-        if (!meta.image) {
-            meta.image = generatePlaceholderAgentProfileImageUrl(parseResult.agentName || '!!');
-        }
         // Generate fullname fallback if no meta fullname specified
         if (!meta.fullname) {
             meta.fullname = parseResult.agentName || createDefaultAgentName(agentSource);
@@ -11791,11 +11987,13 @@
         return {
             agentName: normalizeAgentName(parseResult.agentName || createDefaultAgentName(agentSource)),
             agentHash,
+            permanentId: meta.id,
             personaDescription,
             initialMessage,
             meta,
             links,
             parameters,
+            capabilities,
         };
     }
     /**
@@ -11982,6 +12180,59 @@
     //                  <- [🐱‍🚀] Buttons into genesis book
     // <- TODO: [🐱‍🚀] generateBookBoilerplate and deprecate `DEFAULT_BOOK`
 
+    /**
+     * Generates an image for the agent to use as profile image
+     *
+     * @param agentId - The permanent ID of the agent
+     * @returns The placeholder profile image URL for the agent
+     *
+     * @public exported from `@promptbook/core`
+     */
+    function generatePlaceholderAgentProfileImageUrl(agentIdOrName, agentsServerUrl = CORE_SERVER.urls[0]) {
+        if (typeof agentsServerUrl === 'string') {
+            agentsServerUrl = new URL(agentsServerUrl);
+        }
+        return `${agentsServerUrl.href}agents/${agentIdOrName}/images/default-avatar.png`;
+    }
+    /**
+     * TODO: [🤹] Figure out best placeholder image generator https://i.pravatar.cc/1000?u=568
+     */
+
+    /**
+     * Base58 characters
+     */
+    const BASE58_ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+    /**
+     * Generates random base58 string
+     *
+     * Note: `$` is used to indicate that this function is not a pure function - it is not deterministic
+     * Note: This function is cryptographically secure (it uses crypto.randomBytes internally)
+     *
+     * @param length - length of the string
+     * @returns secure random base58 string
+     *
+     * @private internal helper function
+     */
+    function $randomBase58(length) {
+        let result = '';
+        while (result.length < length) {
+            // Generate enough bytes to cover the remaining length, plus some extra buffer to reduce calls
+            // But simply generating `length - result.length` is fine for small lengths
+            const bytes = crypto.randomBytes(length - result.length);
+            for (let i = 0; i < bytes.length; i++) {
+                const byte = bytes[i];
+                // 58 * 4 = 232
+                // We discard values >= 232 to avoid modulo bias
+                if (byte < 232) {
+                    result += BASE58_ALPHABET[byte % 58];
+                    if (result.length === length)
+                        break;
+                }
+            }
+        }
+        return result;
+    }
+
     // import { getTableName } from '../../../../../apps/agents-server/src/database/getTableName';
     // <- TODO: [🐱‍🚀] Prevent imports from `/apps` -> `/src`
     /**
@@ -12015,19 +12266,20 @@
             const { isVerbose = exports.DEFAULT_IS_VERBOSE } = this.options || {};
             const selectResult = await this.supabaseClient
                 .from(this.getTableName('Agent'))
-                .select('agentName,agentProfile');
+                .select('agentName,agentProfile,permanentId')
+                .is('deletedAt', null);
             if (selectResult.error) {
                 throw new DatabaseError(spaceTrim((block) => `
-                
+
                         Error fetching agents from Supabase:
-                        
+
                         ${block(selectResult.error.message)}
                     `));
             }
             if (isVerbose) {
                 console.info(`Found ${selectResult.data.length} agents in directory`);
             }
-            return selectResult.data.map(({ agentName, agentProfile }) => {
+            return selectResult.data.map(({ agentName, agentProfile, permanentId }) => {
                 if (isVerbose && agentProfile.agentName !== agentName) {
                     console.warn(spaceTrim(`
                         Agent name mismatch for agent "${agentName}". Using name from database.
@@ -12039,26 +12291,42 @@
                 return {
                     ...agentProfile,
                     agentName,
+                    permanentId: permanentId || agentProfile.permanentId,
                 };
             });
         }
         /**
-         * [🐱‍🚀]@@@
+         * Retrieves the permanent ID of an agent by its name or permanent ID.
          */
-        async getAgentSource(agentName) {
+        async getAgentPermanentId(agentNameOrPermanentId) {
+            const selectResult = await this.supabaseClient
+                .from(this.getTableName('Agent'))
+                .select('permanentId')
+                .or(`agentName.eq.${agentNameOrPermanentId},permanentId.eq.${agentNameOrPermanentId}`)
+                .single();
+            if (selectResult.error || !selectResult.data) {
+                throw new NotFoundError(`Agent with name not id "${agentNameOrPermanentId}" not found`);
+            }
+            return selectResult.data.permanentId;
+        }
+        /**
+         * Retrieves the source code of an agent by its name or permanent ID.
+         */
+        async getAgentSource(agentNameOrPermanentId) {
             const selectResult = await this.supabaseClient
                 .from(this.getTableName('Agent'))
                 .select('agentSource')
-                .eq('agentName', agentName);
+                .or(`agentName.eq.${agentNameOrPermanentId},permanentId.eq.${agentNameOrPermanentId}`)
+                .is('deletedAt', null);
             if (selectResult.data && selectResult.data.length === 0) {
-                throw new NotFoundError(`Agent "${agentName}" not found`);
+                throw new NotFoundError(`Agent "${agentNameOrPermanentId}" not found`);
             }
             else if (selectResult.data && selectResult.data.length > 1) {
-                throw new UnexpectedError(`More agents with agentName="${agentName}" found`);
+                throw new UnexpectedError(`More agents with name or id "${agentNameOrPermanentId}" found`);
             }
             else if (selectResult.error) {
                 throw new DatabaseError(spaceTrim((block) => `
-                        Error fetching agent "${agentName}" from Supabase:
+                        Error fetching agent "${agentNameOrPermanentId}" from Supabase:
                         
                         ${block(selectResult.error.message)}
                     `));
@@ -12071,12 +12339,26 @@
          * Note: You can set 'PARENT' in the agent source to inherit from another agent in the collection.
          */
         async createAgent(agentSource) {
-            const agentProfile = parseAgentSource(agentSource);
+            let agentProfile = parseAgentSource(agentSource);
             //     <- TODO: [🕛]
+            // 1. Extract permanentId from the source if present
+            let { permanentId } = agentProfile;
+            // 2. Remove META ID from the source
+            const lines = agentSource.split('\n');
+            const strippedLines = lines.filter((line) => !line.trim().startsWith('META ID '));
+            if (lines.length !== strippedLines.length) {
+                agentSource = strippedLines.join('\n');
+                // 3. Re-parse the agent source to get the correct hash and other info
+                agentProfile = parseAgentSource(agentSource);
+            }
             const { agentName, agentHash } = agentProfile;
+            if (!permanentId) {
+                permanentId = $randomBase58(14);
+            }
             const insertAgentResult = await this.supabaseClient.from(this.getTableName('Agent')).insert({
                 agentName,
                 agentHash,
+                permanentId,
                 agentProfile,
                 createdAt: new Date().toISOString(),
                 updatedAt: null,
@@ -12094,27 +12376,29 @@
             await this.supabaseClient.from(this.getTableName('AgentHistory')).insert({
                 createdAt: new Date().toISOString(),
                 agentName,
+                permanentId,
                 agentHash,
                 previousAgentHash: null,
                 agentSource,
                 promptbookEngineVersion: PROMPTBOOK_ENGINE_VERSION,
             });
             // <- TODO: [🧠] What to do with `insertAgentHistoryResult.error`, ignore? wait?
-            return agentProfile;
+            return { ...agentProfile, permanentId };
         }
         /**
          * Updates an existing agent in the collection
          */
-        async updateAgentSource(agentName, agentSource) {
+        async updateAgentSource(permanentId, agentSource) {
+            console.log('!!! updateAgentSource', { permanentId });
             const selectPreviousAgentResult = await this.supabaseClient
                 .from(this.getTableName('Agent'))
-                .select('agentHash,agentName')
-                .eq('agentName', agentName)
+                .select('agentHash,agentName,permanentId')
+                .eq('permanentId', permanentId)
                 .single();
             if (selectPreviousAgentResult.error) {
                 throw new DatabaseError(spaceTrim((block) => `
                 
-                        Error fetching agent "${agentName}" from Supabase:
+                        Error fetching agent "${permanentId}" from Supabase:
                         
                         ${block(selectPreviousAgentResult.error.message)}
                     `));
@@ -12122,26 +12406,48 @@
             }
             selectPreviousAgentResult.data.agentName;
             const previousAgentHash = selectPreviousAgentResult.data.agentHash;
-            const agentProfile = parseAgentSource(agentSource);
+            const previousPermanentId = selectPreviousAgentResult.data.permanentId;
+            let agentProfile = parseAgentSource(agentSource);
             //     <- TODO: [🕛]
-            const { agentHash } = agentProfile;
+            // 1. Extract permanentId from the source if present
+            let { permanentId: newPermanentId } = agentProfile;
+            // 2. Remove META ID from the source
+            const lines = agentSource.split('\n');
+            const strippedLines = lines.filter((line) => !line.trim().startsWith('META ID '));
+            if (lines.length !== strippedLines.length) {
+                agentSource = strippedLines.join('\n');
+                // 3. Re-parse the agent source to get the correct hash and other info
+                agentProfile = parseAgentSource(agentSource);
+            }
+            const { agentHash, agentName } = agentProfile;
+            if (!newPermanentId && previousPermanentId) {
+                newPermanentId = previousPermanentId;
+            }
+            if (!newPermanentId) {
+                newPermanentId = $randomBase58(14);
+            }
+            if (newPermanentId !== permanentId) {
+                // [🧠] Should be allowed to change permanentId?
+                throw new UnexpectedError(`Permanent ID mismatch: "${permanentId}" (argument) !== "${newPermanentId}" (in source)`);
+            }
             const updateAgentResult = await this.supabaseClient
                 .from(this.getTableName('Agent'))
                 .update({
                 // TODO: [🐱‍🚀] Compare not update> agentName: agentProfile.agentName || '[🐱‍🚀]' /* <- TODO: [🐱‍🚀] Remove */,
+                permanentId,
                 agentProfile,
                 updatedAt: new Date().toISOString(),
                 agentHash: agentProfile.agentHash,
                 agentSource,
                 promptbookEngineVersion: PROMPTBOOK_ENGINE_VERSION,
             })
-                .eq('agentName', agentName);
+                .eq('permanentId', permanentId);
             // console.log('[🐱‍🚀] updateAgent', updateResult);
             // console.log('[🐱‍🚀] old', oldAgentSource);
             // console.log('[🐱‍🚀] new', newAgentSource);
             if (updateAgentResult.error) {
                 throw new DatabaseError(spaceTrim((block) => `
-                        Error updating agent "${agentName}" in Supabase:
+                        Error updating agent "${permanentId}" in Supabase:
                         
                         ${block(updateAgentResult.error.message)}
                     `));
@@ -12149,6 +12455,7 @@
             await this.supabaseClient.from(this.getTableName('AgentHistory')).insert({
                 createdAt: new Date().toISOString(),
                 agentName,
+                permanentId,
                 agentHash,
                 previousAgentHash,
                 agentSource,
@@ -12156,101 +12463,119 @@
             });
             // <- TODO: [🧠] What to do with `insertAgentHistoryResult.error`, ignore? wait?
         }
-        // TODO: [🐱‍🚀] public async getAgentSourceSubject(agentName: string_agent_name): Promise<BehaviorSubject<string_book>>
+        // TODO: [🐱‍🚀] public async getAgentSourceSubject(permanentId: string_agent_permanent_id): Promise<BehaviorSubject<string_book>>
         //            Use Supabase realtime logic
         /**
-         * Deletes an agent from the collection
+         * List agents that are soft deleted (deletedAt IS NOT NULL)
          */
-        async deleteAgent(agentName) {
-            const deleteResult = await this.supabaseClient
+        async listDeletedAgents() {
+            const { isVerbose = exports.DEFAULT_IS_VERBOSE } = this.options || {};
+            const selectResult = await this.supabaseClient
                 .from(this.getTableName('Agent'))
-                .delete()
-                .eq('agentName', agentName);
-            if (deleteResult.error) {
+                .select('agentName,agentProfile,permanentId')
+                .not('deletedAt', 'is', null);
+            if (selectResult.error) {
                 throw new DatabaseError(spaceTrim((block) => `
-                        Error deleting agent "${agentName}" from Supabase:
-                        
-                        ${block(deleteResult.error.message)}
-                    `));
+                    Error fetching deleted agents from Supabase:
+
+                    ${block(selectResult.error.message)}
+                `));
+            }
+            if (isVerbose) {
+                console.info(`Found ${selectResult.data.length} deleted agents in directory`);
             }
+            return selectResult.data.map(({ agentName, agentProfile, permanentId }) => {
+                if (isVerbose && agentProfile.agentName !== agentName) {
+                    console.warn(spaceTrim(`
+                        Agent name mismatch for agent "${agentName}". Using name from database.
+
+                        agentName: "${agentName}"
+                        agentProfile.agentName: "${agentProfile.agentName}"
+                    `));
+                }
+                return {
+                    ...agentProfile,
+                    agentName,
+                    permanentId: permanentId || agentProfile.permanentId,
+                };
+            });
         }
         /**
          * List history of an agent
          */
-        async listAgentHistory(agentName) {
+        async listAgentHistory(permanentId) {
             const result = await this.supabaseClient
                 .from(this.getTableName('AgentHistory'))
                 .select('id, createdAt, agentHash, promptbookEngineVersion')
-                .eq('agentName', agentName)
+                .eq('permanentId', permanentId)
                 .order('createdAt', { ascending: false });
             if (result.error) {
                 throw new DatabaseError(spaceTrim((block) => `
-                    Error listing history for agent "${agentName}" from Supabase:
-                    
+                    Error listing history for agent "${permanentId}" from Supabase:
+
                     ${block(result.error.message)}
                 `));
             }
             return result.data;
         }
         /**
-         * List agents that are in history but not in the active agents list
+         * Restore a soft-deleted agent by setting deletedAt to NULL
          */
-        async listDeletedAgents() {
-            const historyNamesResult = await this.supabaseClient.from(this.getTableName('AgentHistory')).select('agentName');
-            const currentNamesResult = await this.supabaseClient.from(this.getTableName('Agent')).select('agentName');
-            if (historyNamesResult.error) {
-                throw new DatabaseError(spaceTrim((block) => `
-                    Error fetching agent history names from Supabase:
-                    
-                    ${block(historyNamesResult.error.message)}
-                `));
-            }
-            if (currentNamesResult.error) {
+        async restoreAgent(permanentId) {
+            const updateResult = await this.supabaseClient
+                .from(this.getTableName('Agent'))
+                .update({ deletedAt: null })
+                .eq('permanentId', permanentId)
+                .not('deletedAt', 'is', null);
+            if (updateResult.error) {
                 throw new DatabaseError(spaceTrim((block) => `
-                    Error fetching current agent names from Supabase:
-                    
-                    ${block(currentNamesResult.error.message)}
+                    Error restoring agent "${permanentId}" from Supabase:
+
+                    ${block(updateResult.error.message)}
                 `));
             }
-            const currentNames = new Set(currentNamesResult.data.map((d) => d.agentName));
-            const deletedNames = new Set();
-            for (const { agentName } of historyNamesResult.data) {
-                if (!currentNames.has(agentName)) {
-                    deletedNames.add(agentName);
-                }
-            }
-            return Array.from(deletedNames);
         }
         /**
-         * Restore an agent from history
+         * Restore an agent from a specific history entry
+         *
+         * This will update the current agent with the source from the history entry
          */
-        async restoreAgent(historyId) {
+        async restoreAgentFromHistory(historyId) {
+            // First, get the history entry
             const historyResult = await this.supabaseClient
                 .from(this.getTableName('AgentHistory'))
-                .select('*')
+                .select('permanentId, agentSource')
                 .eq('id', historyId)
                 .single();
             if (historyResult.error) {
                 throw new DatabaseError(spaceTrim((block) => `
-                    Error fetching agent history item "${historyId}" from Supabase:
-                    
+                    Error fetching history entry with id "${historyId}" from Supabase:
+
                     ${block(historyResult.error.message)}
                 `));
             }
-            const { agentName, agentSource } = historyResult.data;
-            // Check if agent exists
-            const agentResult = await this.supabaseClient
-                .from(this.getTableName('Agent'))
-                .select('id')
-                .eq('agentName', agentName)
-                .single();
-            if (agentResult.data) {
-                // Update
-                await this.updateAgentSource(agentName, agentSource);
+            if (!historyResult.data) {
+                throw new NotFoundError(`History entry with id "${historyId}" not found`);
             }
-            else {
-                // Insert (Restore from deleted)
-                await this.createAgent(agentSource);
+            const { permanentId, agentSource } = historyResult.data;
+            // Update the agent with the source from the history entry
+            await this.updateAgentSource(permanentId, agentSource);
+        }
+        /**
+         * Soft delete an agent by setting deletedAt to current timestamp
+         */
+        async deleteAgent(permanentId) {
+            const updateResult = await this.supabaseClient
+                .from(this.getTableName('Agent'))
+                .update({ deletedAt: new Date().toISOString() })
+                .eq('permanentId', permanentId)
+                .is('deletedAt', null);
+            if (updateResult.error) {
+                throw new DatabaseError(spaceTrim((block) => `
+                    Error deleting agent "${permanentId}" from Supabase:
+
+                    ${block(updateResult.error.message)}
+                `));
             }
         }
         /**
@@ -12262,6 +12587,7 @@
         getTableName(tableName) {
             const { tablePrefix = '' } = this.options || {};
             return `${tablePrefix}${tableName}`;
+            // <- TODO: [🏧] DRY
         }
     }
     /**
@@ -13940,11 +14266,7 @@
             // TODO: [🚜] DRY
             if ($taskJson.modelRequirements[command.key] !== undefined) {
                 if ($taskJson.modelRequirements[command.key] === command.value) {
-                    console.warn(`Multiple commands \`MODEL ${{
-                    modelName: 'NAME',
-                    modelVariant: 'VARIANT',
-                    maxTokens: '???',
-                }[command.key]} ${command.value}\` in the task "${$taskJson.title || $taskJson.name}"`);
+                    console.warn(`Multiple commands \`MODEL ${command.key} ${command.value}\` in the task "${$taskJson.title || $taskJson.name}"`);
                     // <- TODO: [🏮] Some standard way how to transform errors into warnings and how to handle non-critical fails during the tasks
                 }
                 else {
@@ -16468,7 +16790,7 @@
                                 ${i + 1}) **${title}** \`${className}\` from \`${packageName}\`
                                     ${morePieces.join('; ')}
                             `);
-        if ($isRunningInNode) {
+        if ($isRunningInNode()) {
             if (isInstalled && isFullyConfigured) {
                 providerMessage = colors__default["default"].green(providerMessage);
             }
@@ -16673,6 +16995,9 @@
                 case 'EMBEDDING':
                     promptResult = await llmTools.callEmbeddingModel(prompt);
                     break variant;
+                case 'IMAGE_GENERATION':
+                    promptResult = await llmTools.callImageGenerationModel(prompt);
+                    break variant;
                 // <- case [🤖]:
                 default:
                     throw new PipelineExecutionError(`Unknown model variant "${prompt.modelRequirements.modelVariant}"`);
@@ -16709,12 +17034,13 @@
                     }
                 }
                 catch (error) {
+                    assertsError(error);
                     // If validation throws an unexpected error, don't cache
                     shouldCache = false;
                     if (isVerbose) {
                         console.info('Not caching result due to validation error for key:', key, {
                             content: promptResult.content,
-                            validationError: error instanceof Error ? error.message : String(error),
+                            validationError: serializeError(error),
                         });
                     }
                 }
@@ -16760,6 +17086,11 @@
                 return /* not await */ callCommonModel(prompt);
             };
         }
+        if (llmTools.callImageGenerationModel !== undefined) {
+            proxyTools.callImageGenerationModel = async (prompt) => {
+                return /* not await */ callCommonModel(prompt);
+            };
+        }
         // <- Note: [🤖]
         return proxyTools;
     }
@@ -16798,6 +17129,11 @@
                 throw new LimitReachedError('Cannot call `callEmbeddingModel` because you are not allowed to spend any cost');
             };
         }
+        if (proxyTools.callImageGenerationModel !== undefined) {
+            proxyTools.callImageGenerationModel = async (prompt) => {
+                throw new LimitReachedError('Cannot call `callImageGenerationModel` because you are not allowed to spend any cost');
+            };
+        }
         // <- Note: [🤖]
         return proxyTools;
     }
@@ -17869,7 +18205,7 @@
             let threadMessages = [];
             if ('thread' in prompt && Array.isArray(prompt.thread)) {
                 threadMessages = prompt.thread.map((msg) => ({
-                    role: msg.role === 'assistant' ? 'assistant' : 'user',
+                    role: msg.sender === 'assistant' ? 'assistant' : 'user',
                     content: msg.content,
                 }));
             }
@@ -18282,13 +18618,14 @@
             const modelName = currentModelRequirements.modelName || this.getDefaultImageGenerationModel().modelName;
             const modelSettings = {
                 model: modelName,
-                // size: currentModelRequirements.size,
-                // quality: currentModelRequirements.quality,
-                // style: currentModelRequirements.style,
+                size: currentModelRequirements.size,
+                quality: currentModelRequirements.quality,
+                style: currentModelRequirements.style,
             };
             const rawPromptContent = templateParameters(content, { ...parameters, modelName });
             const rawRequest = {
                 ...modelSettings,
+                size: modelSettings.size || '1024x1024',
                 prompt: rawPromptContent,
                 user: (_a = this.options.userId) === null || _a === void 0 ? void 0 : _a.toString(),
                 response_format: 'url', // TODO: [🧠] Maybe allow b64_json
@@ -19307,6 +19644,11 @@
              * Links found in the agent source
              */
             this.links = [];
+            /**
+             * Capabilities of the agent
+             * This is parsed from commitments like USE BROWSER, USE SEARCH ENGINE, KNOWLEDGE, etc.
+             */
+            this.capabilities = [];
             /**
              * Metadata like image or color
              */
@@ -19316,11 +19658,12 @@
             this.agentSource = agentSource;
             this.agentSource.subscribe((source) => {
                 this.updateAgentSource(source);
-                const { agentName, personaDescription, initialMessage, links, meta } = parseAgentSource(source);
+                const { agentName, personaDescription, initialMessage, links, meta, capabilities } = parseAgentSource(source);
                 this._agentName = agentName;
                 this.personaDescription = personaDescription;
                 this.initialMessage = initialMessage;
                 this.links = links;
+                this.capabilities = capabilities;
                 this.meta = { ...this.meta, ...meta };
             });
         }
@@ -19394,9 +19737,52 @@
                 ${block(result.content)}
 
             `);
+            // Extract knowledge
+            let knowledgeBlock = '';
+            try {
+                const extractionPrompt = {
+                    title: 'Knowledge Extraction',
+                    modelRequirements: {
+                        modelVariant: 'CHAT',
+                    },
+                    content: spaceTrim__default["default"]((block) => `
+                        You are an AI agent that is learning from a conversation.
+
+                        Here is the conversation so far:
+
+                        User: ${block(prompt.content)}
+                        Agent: ${block(result.content)}
+
+                        Extract any new knowledge, facts, or important information that should be remembered for future interactions.
+                        Format the output as a list of KNOWLEDGE blocks.
+                        If there is no new knowledge, return nothing.
+
+                        Example output:
+                        KNOWLEDGE The user's name is Alice.
+                        KNOWLEDGE The project deadline is next Friday.
+                    `),
+                    pipelineUrl: 'https://github.com/webgptorg/promptbook/blob/main/prompts/knowledge-extraction.ptbk.md',
+                    parameters: {},
+                };
+                if (this.options.llmTools.callChatModel) {
+                    const extractionResult = await this.options.llmTools.callChatModel(extractionPrompt);
+                    const extractedContent = extractionResult.content;
+                    if (extractedContent.includes('KNOWLEDGE')) {
+                        knowledgeBlock = '\n\n' + spaceTrim__default["default"](extractedContent);
+                    }
+                }
+                else {
+                    // TODO: [🧠] Fallback to callChatModelStream if callChatModel is not available
+                }
+            }
+            catch (error) {
+                if (this.options.isVerbose) {
+                    console.warn('Failed to extract knowledge', error);
+                }
+            }
             // Append to the current source
             const currentSource = this.agentSource.value;
-            const newSource = padBook(validateBook(spaceTrim__default["default"](currentSource) + '\n\n' + learningExample));
+            const newSource = padBook(validateBook(spaceTrim__default["default"](currentSource) + '\n\n' + learningExample + knowledgeBlock));
             // Update the source (which will trigger the subscription and update the underlying tools)
             this.agentSource.next(newSource);
             return result;
@@ -20848,7 +21234,7 @@
         'Serious and focused AI consultant.',
     ];
     /**
-     * @@@@
+     * Generates a random agent persona description.
      *
      * @private internal helper function
      */
@@ -21187,6 +21573,7 @@
     exports.BoilerplateFormfactorDefinition = BoilerplateFormfactorDefinition;
     exports.CLAIM = CLAIM;
     exports.CLI_APP_ID = CLI_APP_ID;
+    exports.CORE_SERVER = CORE_SERVER;
     exports.CallbackInterfaceTools = CallbackInterfaceTools;
     exports.ChatbotFormfactorDefinition = ChatbotFormfactorDefinition;
     exports.CollectionError = CollectionError;