@promptbook/cli 0.103.0-46 → 0.103.0-48

package/esm/index.es.js

@@ -47,7 +47,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.103.0-46';
+const PROMPTBOOK_ENGINE_VERSION = '0.103.0-48';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -60,15 +60,20 @@ const PROMPTBOOK_ENGINE_VERSION = '0.103.0-46';
  */
 const REMOTE_SERVER_URLS = [
     {
-        title: 'Promptbook',
-        description: `Servers of Promptbook.studio`,
+        title: 'Promptbook.Studio',
+        description: `Server of Promptbook.studio`,
         owner: 'AI Web, LLC <legal@ptbk.io> (https://www.ptbk.io/)',
-        isAnonymousModeAllowed: true,
         urls: [
             'https://promptbook.s5.ptbk.io/',
             // Note: Servers 1-4 are not running
         ],
     },
+    {
+        title: 'Testing Agents',
+        description: `Testing Agents server on Vercel`,
+        owner: 'AI Web, LLC <legal@ptbk.io> (https://www.ptbk.io/)',
+        urls: ['https://s6.ptbk.io/'],
+    },
     /*
     Note: Working on older version of Promptbook and not supported anymore
     {
@@ -326,9 +331,6 @@ function checkChannelValue(channelName, value) {
         throw new Error(`${channelName} channel is greater than 255, it is ${value}`);
     }
 }
-/**
- * TODO: [🧠][🚓] Is/which combination it better to use asserts/check, validate or is utility function?
- */
 
 /**
  * Color object represents an RGB color with alpha channel
@@ -2936,6 +2938,8 @@ function removeDiacritics(input) {
 /**
  * Converts a given text to kebab-case format.
  *
+ * Note: [🔂] This function is idempotent.
+ *
  * @param text The text to be converted.
  * @returns The kebab-case formatted string.
  * @example 'hello-world'
@@ -3005,6 +3009,8 @@ function removeEmojis(text) {
 /**
  * Converts a title string into a normalized name.
  *
+ * Note: [🔂] This function is idempotent.
+ *
  * @param value The title string to be converted to a name.
  * @returns A normalized name derived from the input title.
  * @example 'Hello World!' -> 'hello-world'
@@ -10015,6 +10021,8 @@ const expectCommandParser = {
 /**
  * Normalizes a given text to camelCase format.
  *
+ * Note: [🔂] This function is idempotent.
+ *
  * @param text The text to be normalized.
  * @param _isFirstLetterCapital Whether the first letter should be capitalized.
  * @returns The camelCase formatted string.
@@ -13023,6 +13031,9 @@ function nameToUriParts(name) {
 }
 
 /**
+ * Normalizes a given text to PascalCase format.
+ *
+ * Note: [🔂] This function is idempotent.
  *
  * @param text @public exported from `@promptbook/utils`
  * @returns
@@ -15080,16 +15091,18 @@ function $initializeRunCommand(program) {
  *
  * @see https://github.com/webgptorg/promptbook#remote-server
  * @public exported from `@promptbook/remote-server`
- * <- TODO: !!!! Maybe change to `@promptbook/agent-server`
+ * <- TODO: !!!! Change to `@promptbook/agent-server`
  */
 async function startAgentServer(options) {
     const { port = 4440 } = options;
     // TODO: !!!! [🌕]
+    const agentsServerRoot = join(__dirname, '../apps/agents-server');
     console.trace(`!!! Starting agents server on port ${port}...`);
     console.log(`!!! cwd`, process.cwd());
     console.log(`!!! __dirname`, __dirname);
+    console.log(`!!! agentsServerRoot`, agentsServerRoot);
     await $execCommand({
-        cwd: './apps/agents-server',
+        cwd: agentsServerRoot,
         command: `next dev --port ${port} `,
         isVerbose: true,
     });
@@ -16390,8 +16403,7 @@ function startRemoteServer(options) {
     };
 }
 /**
- * TODO !!!! Add agent
- * TODO: !!!! Allow to chat with agents directly via remote server
+
  * TODO: [🕋] Use here `aboutPromptbookInformation`
  * TODO: [🌡] Add CORS and security - probably via `helmet`
  * TODO: Split this file into multiple functions - handler for each request
@@ -17512,17 +17524,17 @@ const OPENAI_MODELS = exportJson({
         },
         /**/
         /*/
-      {
-          modelTitle: 'tts-1-hd-1106',
-          modelName: 'tts-1-hd-1106',
-      },
-      /**/
+        {
+            modelTitle: 'tts-1-hd-1106',
+            modelName: 'tts-1-hd-1106',
+        },
+        /**/
         /*/
-      {
-          modelTitle: 'tts-1-hd',
-          modelName: 'tts-1-hd',
-      },
-      /**/
+        {
+            modelTitle: 'tts-1-hd',
+            modelName: 'tts-1-hd',
+        },
+        /**/
         /**/
         {
             modelVariant: 'CHAT',
@@ -18842,26 +18854,6 @@ const GOOGLE_MODELS = exportJson({
                 output: pricing(`$0.45 / 1M tokens`),
             },
         },
-        {
-            modelVariant: 'CHAT',
-            modelTitle: 'Gemini 2.0 Flash',
-            modelName: 'gemini-2.0-flash',
-            modelDescription: 'Fast, efficient model with 128K context window optimized for rapid response times. Balances performance and cost with 2x lower latency than Pro models while maintaining strong capabilities in text generation, code completion, and logical reasoning. Excellent for interactive applications, chatbots, and services requiring quick responses with good quality.',
-            pricing: {
-                prompt: pricing(`$0.35 / 1M tokens`),
-                output: pricing(`$1.05 / 1M tokens`),
-            },
-        },
-        {
-            modelVariant: 'CHAT',
-            modelTitle: 'Gemini 2.0 Flash Lite',
-            modelName: 'gemini-2.0-flash-lite',
-            modelDescription: 'Streamlined version of Gemini 2.0 Flash with 64K context window, designed for extremely low-latency applications. Features 40% smaller model size and 3x faster inference while retaining core capabilities for text and simple reasoning tasks. Perfect for mobile applications, edge deployments, and high-volume services with strict latency requirements.',
-            pricing: {
-                prompt: pricing(`$0.20 / 1M tokens`),
-                output: pricing(`$0.60 / 1M tokens`),
-            },
-        },
         {
             modelVariant: 'CHAT',
             modelTitle: 'Gemini 2.0 Flash Thinking',
@@ -20398,7 +20390,7 @@ class OpenAiExecutionTools extends OpenAiCompatibleExecutionTools {
  *
  * This is useful for calling OpenAI API with a single assistant, for more wide usage use `OpenAiExecutionTools`.
  *
- * Note: [🦖] There are several different things in Promptbook:
+ * !!! Note: [🦖] There are several different things in Promptbook:
  * - `Agent` - which represents an AI Agent with its source, memories, actions, etc. Agent is a higher-level abstraction which is internally using:
  * - `LlmExecutionTools` - which wraps one or more LLM models and provides an interface to execute them
  * - `AgentLlmExecutionTools` - which is a specific implementation of `LlmExecutionTools` that wraps another LlmExecutionTools and applies agent-specific system prompts and requirements
@@ -20504,17 +20496,21 @@ class OpenAiAssistantExecutionTools extends OpenAiExecutionTools {
                 console.info('connect', stream.currentEvent);
             }
         });
+        /*
         stream.on('messageDelta', (messageDelta) => {
-            var _a;
-            if (this.options.isVerbose &&
+            if (
+                this.options.isVerbose &&
                 messageDelta &&
                 messageDelta.content &&
                 messageDelta.content[0] &&
-                messageDelta.content[0].type === 'text') {
-                console.info('messageDelta', (_a = messageDelta.content[0].text) === null || _a === void 0 ? void 0 : _a.value);
+                messageDelta.content[0].type === 'text'
+            ) {
+                console.info('messageDelta', messageDelta.content[0].text?.value);
             }
+
             // <- TODO: [🐚] Make streaming and running tasks working
         });
+        */
         stream.on('messageCreated', (message) => {
             if (this.options.isVerbose) {
                 console.info('messageCreated', message);
@@ -20569,15 +20565,19 @@ class OpenAiAssistantExecutionTools extends OpenAiExecutionTools {
             },
         });
     }
-    async playground() {
+    /*
+    public async playground() {
         const client = await this.getClient();
+
         // List all assistants
         const assistants = await client.beta.assistants.list();
         console.log('!!! Assistants:', assistants);
+
         // Get details of a specific assistant
         const assistantId = 'asst_MO8fhZf4dGloCfXSHeLcIik0';
         const assistant = await client.beta.assistants.retrieve(assistantId);
         console.log('!!! Assistant Details:', assistant);
+
         // Update an assistant
         const updatedAssistant = await client.beta.assistants.update(assistantId, {
             name: assistant.name + '(M)',
@@ -20587,71 +20587,103 @@ class OpenAiAssistantExecutionTools extends OpenAiExecutionTools {
             },
         });
         console.log('!!! Updated Assistant:', updatedAssistant);
+
         await forEver();
     }
+    */
+    /**
+     * Get an existing assistant tool wrapper
+     */
+    getAssistant(assistantId) {
+        return new OpenAiAssistantExecutionTools({
+            ...this.options,
+            assistantId,
+        });
+    }
     async createNewAssistant(options) {
         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 } = options;
+        const { name, instructions, knowledgeSources } = options;
         const client = await this.getClient();
-        /*/
-        //TODO: !!!
-        async function downloadFile(url: string, folder = './tmp'): Promise<string> {
-            const filename = path.basename(url.split('?')[0]);
-            const filepath = path.join(folder, filename);
-
-            if (!fs.existsSync(folder)) fs.mkdirSync(folder);
-
-            const res = await fetch(url);
-            if (!res.ok) throw new Error(`Download error: ${url}`);
-            const buffer = await res.arrayBuffer();
-            fs.writeFileSync(filepath, Buffer.from(buffer));
-            console.log(`📥 File downloaded: ${filename}`);
-
-            return filepath;
-        }
-
-        async function uploadFileToOpenAI(filepath: string) {
-            const file = await client.files.create({
-                file: fs.createReadStream(filepath),
-                purpose: 'assistants',
+        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...`);
+            }
+            // Create a vector store
+            const vectorStore = await client.beta.vectorStores.create({
+                name: `${name} Knowledge Base`,
             });
-            console.log(`⬆️  File uploaded to OpenAI: ${file.filename} (${file.id})`);
-            return file;
-        }
-
-        // 🌐 URL addresses of files to upload
-        const fileUrls = [
-            'https://raw.githubusercontent.com/vercel/next.js/canary/packages/next/README.md',
-            'https://raw.githubusercontent.com/openai/openai-cookbook/main/examples/How_to_call_the_Assistants_API_with_Node.js.ipynb',
-        ];
-
-        // 1️⃣ Download files from URL
-        const localFiles = [];
-        for (const url of fileUrls) {
-            const filepath = await downloadFile(url);
-            localFiles.push(filepath);
-        }
-
-        // 2️⃣ Upload files to OpenAI
-        const uploadedFiles = [];
-        for (const filepath of localFiles) {
-            const file = await uploadFileToOpenAI(filepath);
-            uploadedFiles.push(file.id);
+            vectorStoreId = vectorStore.id;
+            if (this.options.isVerbose) {
+                console.info(`✅ Vector store created: ${vectorStoreId}`);
+            }
+            // Upload files from knowledge sources to the vector store
+            const fileStreams = [];
+            for (const source of knowledgeSources) {
+                try {
+                    // Check if it's a URL
+                    if (source.startsWith('http://') || source.startsWith('https://')) {
+                        // Download the file
+                        const response = await fetch(source);
+                        if (!response.ok) {
+                            console.error(`Failed to download ${source}: ${response.statusText}`);
+                            continue;
+                        }
+                        const buffer = await response.arrayBuffer();
+                        const filename = source.split('/').pop() || 'downloaded-file';
+                        const blob = new Blob([buffer]);
+                        const file = new File([blob], filename);
+                        fileStreams.push(file);
+                    }
+                    else {
+                        // Assume it's a local file path
+                        // Note: This will work in Node.js environment
+                        // For browser environments, this would need different handling
+                        const fs = await import('fs');
+                        const fileStream = fs.createReadStream(source);
+                        fileStreams.push(fileStream);
+                    }
+                }
+                catch (error) {
+                    console.error(`Error processing knowledge source ${source}:`, error);
+                }
+            }
+            // Batch upload files to the vector store
+            if (fileStreams.length > 0) {
+                try {
+                    await client.beta.vectorStores.fileBatches.uploadAndPoll(vectorStoreId, {
+                        files: fileStreams,
+                    });
+                    if (this.options.isVerbose) {
+                        console.info(`✅ Uploaded ${fileStreams.length} files to vector store`);
+                    }
+                }
+                catch (error) {
+                    console.error('Error uploading files to vector store:', error);
+                }
+            }
         }
-        /**/
-        // alert('!!!! Creating new OpenAI assistant');
-        // 3️⃣ Create assistant with uploaded files
-        const assistant = await client.beta.assistants.create({
+        // Create assistant with vector store attached
+        const assistantConfig = {
             name,
             description: 'Assistant created via Promptbook',
             model: 'gpt-4o',
             instructions,
             tools: [/* TODO: [🧠] Maybe add { type: 'code_interpreter' }, */ { type: 'file_search' }],
-            // !!!! file_ids: uploadedFiles,
-        });
+        };
+        // Attach vector store if created
+        if (vectorStoreId) {
+            assistantConfig.tool_resources = {
+                file_search: {
+                    vector_store_ids: [vectorStoreId],
+                },
+            };
+        }
+        const assistant = await client.beta.assistants.create(assistantConfig);
         console.log(`✅ Assistant created: ${assistant.id}`);
         // TODO: !!!! Try listing existing assistants
         // TODO: !!!! Try marking existing assistants by DISCRIMINANT
@@ -20662,6 +20694,95 @@ class OpenAiAssistantExecutionTools extends OpenAiExecutionTools {
             assistantId: assistant.id,
         });
     }
+    async updateAssistant(options) {
+        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 } = options;
+        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...`);
+            }
+            // Create a vector store
+            const vectorStore = await client.beta.vectorStores.create({
+                name: `${name} Knowledge Base`,
+            });
+            vectorStoreId = vectorStore.id;
+            if (this.options.isVerbose) {
+                console.info(`✅ Vector store created: ${vectorStoreId}`);
+            }
+            // Upload files from knowledge sources to the vector store
+            const fileStreams = [];
+            for (const source of knowledgeSources) {
+                try {
+                    // Check if it's a URL
+                    if (source.startsWith('http://') || source.startsWith('https://')) {
+                        // Download the file
+                        const response = await fetch(source);
+                        if (!response.ok) {
+                            console.error(`Failed to download ${source}: ${response.statusText}`);
+                            continue;
+                        }
+                        const buffer = await response.arrayBuffer();
+                        const filename = source.split('/').pop() || 'downloaded-file';
+                        const blob = new Blob([buffer]);
+                        const file = new File([blob], filename);
+                        fileStreams.push(file);
+                    }
+                    else {
+                        // Assume it's a local file path
+                        // Note: This will work in Node.js environment
+                        // For browser environments, this would need different handling
+                        const fs = await import('fs');
+                        const fileStream = fs.createReadStream(source);
+                        fileStreams.push(fileStream);
+                    }
+                }
+                catch (error) {
+                    console.error(`Error processing knowledge source ${source}:`, error);
+                }
+            }
+            // Batch upload files to the vector store
+            if (fileStreams.length > 0) {
+                try {
+                    await client.beta.vectorStores.fileBatches.uploadAndPoll(vectorStoreId, {
+                        files: fileStreams,
+                    });
+                    if (this.options.isVerbose) {
+                        console.info(`✅ Uploaded ${fileStreams.length} files to vector store`);
+                    }
+                }
+                catch (error) {
+                    console.error('Error uploading files to vector store:', error);
+                }
+            }
+        }
+        const assistantUpdate = {
+            name,
+            instructions,
+            tools: [/* TODO: [🧠] Maybe add { type: 'code_interpreter' }, */ { type: 'file_search' }],
+        };
+        if (vectorStoreId) {
+            assistantUpdate.tool_resources = {
+                file_search: {
+                    vector_store_ids: [vectorStoreId],
+                },
+            };
+        }
+        const assistant = await client.beta.assistants.update(assistantId, assistantUpdate);
+        if (this.options.isVerbose) {
+            console.log(`✅ Assistant updated: ${assistant.id}`);
+        }
+        return new OpenAiAssistantExecutionTools({
+            ...this.options,
+            isCreatingNewAssistantsAllowed: false,
+            assistantId: assistant.id,
+        });
+    }
     /**
      * Discriminant for type guards
      */
@@ -22225,40 +22346,6 @@ const _FormattedBookInMarkdownTranspilerRegistration = $bookTranspilersRegister.
  * Note: [💞] Ignore a discrepancy between file name and entity name
  */
 
-/**
- * Creates an empty/basic agent model requirements object
- * This serves as the starting point for the reduce-like pattern
- * where each commitment applies its changes to build the final requirements
- *
- * @public exported from `@promptbook/core`
- */
-function createEmptyAgentModelRequirements() {
-    return {
-        systemMessage: '',
-        // modelName: 'gpt-5',
-        modelName: 'gemini-2.5-flash-lite',
-        temperature: 0.7,
-        topP: 0.9,
-        topK: 50,
-    };
-}
-/**
- * Creates a basic agent model requirements with just the agent name
- * This is used when we have an agent name but no commitments
- *
- * @public exported from `@promptbook/core`
- */
-function createBasicAgentModelRequirements(agentName) {
-    const empty = createEmptyAgentModelRequirements();
-    return {
-        ...empty,
-        systemMessage: `You are ${agentName || 'AI Agent'}`,
-    };
-}
-/**
- * TODO: [🐤] Deduplicate `AgentModelRequirements` and `ModelRequirements` model requirements
- */
-
 /**
  * Generates a regex pattern to match a specific commitment
  *
@@ -22792,23 +22879,19 @@ class KnowledgeCommitmentDefinition extends BaseCommitmentDefinition {
         `);
     }
     applyToAgentModelRequirements(requirements, content) {
-        var _a;
         const trimmedContent = content.trim();
         if (!trimmedContent) {
             return requirements;
         }
         // Check if content is a URL (external knowledge source)
-        if (this.isUrl(trimmedContent)) {
+        if (isValidUrl(trimmedContent)) {
             // Store the URL for later async processing
             const updatedRequirements = {
                 ...requirements,
-                metadata: {
-                    ...requirements.metadata,
-                    knowledgeSources: [
-                        ...(((_a = requirements.metadata) === null || _a === void 0 ? void 0 : _a.knowledgeSources) || []),
-                        trimmedContent,
-                    ],
-                },
+                knowledgeSources: [
+                    ...(requirements.knowledgeSources || []),
+                    trimmedContent,
+                ],
             };
             // Add placeholder information about knowledge sources to system message
             const knowledgeInfo = `Knowledge Source URL: ${trimmedContent} (will be processed for retrieval during chat)`;
@@ -22820,18 +22903,6 @@ class KnowledgeCommitmentDefinition extends BaseCommitmentDefinition {
             return this.appendToSystemMessage(requirements, knowledgeSection, '\n\n');
         }
     }
-    /**
-     * Check if content is a URL
-     */
-    isUrl(content) {
-        try {
-            new URL(content);
-            return true;
-        }
-        catch (_a) {
-            return false;
-        }
-    }
 }
 /**
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -23642,6 +23713,7 @@ class PersonaCommitmentDefinition extends BaseCommitmentDefinition {
             // Keep everything after the PERSONA section
             cleanedMessage = lines.slice(personaEndIndex).join('\n').trim();
         }
+        // TODO: [🕛] There should be `agentFullname` not `agentName`
         // Create new system message with persona at the beginning
         // Format: "You are {agentName}\n{personaContent}"
         // The # PERSONA comment will be removed later by removeCommentsFromSystemMessage
@@ -24129,6 +24201,40 @@ function getCommitmentDefinition(type) {
  * Note: [💞] Ignore a discrepancy between file name and entity name
  */
 
+/**
+ * Creates an empty/basic agent model requirements object
+ * This serves as the starting point for the reduce-like pattern
+ * where each commitment applies its changes to build the final requirements
+ *
+ * @public exported from `@promptbook/core`
+ */
+function createEmptyAgentModelRequirements() {
+    return {
+        systemMessage: '',
+        // modelName: 'gpt-5',
+        modelName: 'gemini-2.5-flash-lite',
+        temperature: 0.7,
+        topP: 0.9,
+        topK: 50,
+    };
+}
+/**
+ * Creates a basic agent model requirements with just the agent name
+ * This is used when we have an agent name but no commitments
+ *
+ * @public exported from `@promptbook/core`
+ */
+function createBasicAgentModelRequirements(agentName) {
+    const empty = createEmptyAgentModelRequirements();
+    return {
+        ...empty,
+        systemMessage: `You are ${agentName || 'AI Agent'}`,
+    };
+}
+/**
+ * TODO: [🐤] Deduplicate `AgentModelRequirements` and `ModelRequirements` model requirements
+ */
+
 /**
  * Parses agent source using the new commitment system with multiline support
  * This function replaces the hardcoded commitment parsing in the original parseAgentSource
@@ -24219,29 +24325,6 @@ function parseAgentSourceWithCommitments(agentSource) {
     };
 }
 
-/**
- * Removes comment lines (lines starting with #) from a system message
- * This is used to clean up the final system message before sending it to the AI model
- * while preserving the original content with comments in metadata
- *
- * @param systemMessage The system message that may contain comment lines
- * @returns The system message with comment lines removed
- *
- * @private - TODO: [🧠] Maybe should be public?
- */
-function removeCommentsFromSystemMessage(systemMessage) {
-    if (!systemMessage) {
-        return systemMessage;
-    }
-    const lines = systemMessage.split('\n');
-    const filteredLines = lines.filter((line) => {
-        const trimmedLine = line.trim();
-        // Remove lines that start with # (comments)
-        return !trimmedLine.startsWith('#');
-    });
-    return filteredLines.join('\n').trim();
-}
-
 /**
  * Parses parameters from text using both supported notations:
  * 1. @Parameter - single word parameter starting with @
@@ -24300,6 +24383,29 @@ function parseParameters(text) {
     return uniqueParameters;
 }
 
+/**
+ * Removes comment lines (lines starting with #) from a system message
+ * This is used to clean up the final system message before sending it to the AI model
+ * while preserving the original content with comments in metadata
+ *
+ * @param systemMessage The system message that may contain comment lines
+ * @returns The system message with comment lines removed
+ *
+ * @private - TODO: [🧠] Maybe should be public?
+ */
+function removeCommentsFromSystemMessage(systemMessage) {
+    if (!systemMessage) {
+        return systemMessage;
+    }
+    const lines = systemMessage.split('\n');
+    const filteredLines = lines.filter((line) => {
+        const trimmedLine = line.trim();
+        // Remove lines that start with # (comments)
+        return !trimmedLine.startsWith('#');
+    });
+    return filteredLines.join('\n').trim();
+}
+
 /**
  * Creates agent model requirements using the new commitment system
  * This function uses a reduce-like pattern where each commitment applies its changes
@@ -24436,6 +24542,36 @@ function generatePlaceholderAgentProfileImageUrl(agentName) {
  * TODO: [🤹] Figure out best placeholder image generator https://i.pravatar.cc/1000?u=568
  */
 
+/**
+ * Computes SHA-256 hash of the agent source
+ *
+ * @public exported from `@promptbook/core`
+ */
+function computeAgentHash(agentSource) {
+    return SHA256(hexEncoder.parse(agentSource /* <- TODO: !!!!! spaceTrim */)).toString( /* hex */);
+}
+
+/**
+ * Normalizes agent name from arbitrary string to valid agent name
+ *
+ * Note: [🔂] This function is idempotent.
+ *
+ * @public exported from `@promptbook/core`
+ */
+function normalizeAgentName(rawAgentName) {
+    return titleToName(spaceTrim(rawAgentName));
+}
+
+/**
+ * Creates temporary default agent name based on agent source hash
+ *
+ * @public exported from `@promptbook/core`
+ */
+function createDefaultAgentName(agentSource) {
+    const agentHash = computeAgentHash(agentSource);
+    return normalizeAgentName(`Agent ${agentHash.substring(0, 6)}`);
+}
+
 /**
  * Parses basic information from agent source
  *
@@ -24478,8 +24614,10 @@ function parseAgentSource(agentSource) {
     // Parse parameters using unified approach - both @Parameter and {parameter} notations
     // are treated as the same syntax feature with unified representation
     const parameters = parseParameters(agentSource);
+    const agentHash = computeAgentHash(agentSource);
     return {
-        agentName: parseResult.agentName,
+        agentName: normalizeAgentName(parseResult.agentName || createDefaultAgentName(agentSource)),
+        agentHash,
         personaDescription,
         meta,
         parameters,
@@ -24699,7 +24837,7 @@ const OpenAiSdkTranspiler = {
                         });
 
                         const answer = response.choices[0].message.content;
-                        console.log('\\n🧠 ${agentName}:', answer, '\\n');
+                        console.log('\\n🧠 ${agentName /* <- TODO: [🕛] There should be `agentFullname` not `agentName` */}:', answer, '\\n');
 
                         chatHistory.push({ role: 'assistant', content: answer });
                         promptUser();
@@ -24718,7 +24856,7 @@ const OpenAiSdkTranspiler = {
 
                     (async () => {
                         await setupKnowledge();
-                        console.log("🤖 Chat with ${agentName} (type 'exit' to quit)\\n");
+                        console.log("🤖 Chat with ${agentName /* <- TODO: [🕛] There should be `agentFullname` not `agentName` */} (type 'exit' to quit)\\n");
                         promptUser();
                     })();
                 `);
@@ -24765,7 +24903,7 @@ const OpenAiSdkTranspiler = {
                     });
 
                     const answer = response.choices[0].message.content;
-                    console.log('\\n🧠 ${agentName}:', answer, '\\n');
+                    console.log('\\n🧠 ${agentName /* <- TODO: [🕛] There should be `agentFullname` not `agentName` */}:', answer, '\\n');
 
                     chatHistory.push({ role: 'assistant', content: answer });
                     promptUser();
@@ -24782,7 +24920,7 @@ const OpenAiSdkTranspiler = {
                     });
                 }
 
-                console.log("🤖 Chat with ${agentName} (type 'exit' to quit)\\n");
+                console.log("🤖 Chat with ${agentName /* <- TODO: [🕛] There should be `agentFullname` not `agentName` */} (type 'exit' to quit)\\n");
                 promptUser();
 
             `);
@@ -24798,7 +24936,7 @@ const OpenAiSdkTranspiler = {
  * @public exported from `@promptbook/wizard`
  * @public exported from `@promptbook/cli`
  *
- * TODO: !!!! Which package should export this?
+ * TODO: [🧠] Which package should export this?
  */
 const _OpenAiSdkTranspilerRegistration = $bookTranspilersRegister.register(OpenAiSdkTranspiler);
 /**