@promptbook/node 0.110.0-3 → 0.110.0-5

package/esm/index.es.js

@@ -34,7 +34,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.110.0-3';
+const PROMPTBOOK_ENGINE_VERSION = '0.110.0-5';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -16974,11 +16974,16 @@ function createTeamToolFunction(entry) {
         const request = buildTeammateRequest(message, args.context);
         let response = '';
         let error = null;
+        let toolCalls;
         try {
             const remoteAgent = await getRemoteTeammateAgent(entry.teammate.url);
             const prompt = buildTeammatePrompt(request);
             const teammateResult = await remoteAgent.callChatModel(prompt);
             response = teammateResult.content || '';
+            toolCalls =
+                'toolCalls' in teammateResult && Array.isArray(teammateResult.toolCalls)
+                    ? teammateResult.toolCalls
+                    : undefined;
         }
         catch (err) {
             error = err instanceof Error ? err.message : String(err);
@@ -16988,6 +16993,7 @@ function createTeamToolFunction(entry) {
             teammate: teammateMetadata,
             request,
             response: teammateReply,
+            toolCalls: toolCalls && toolCalls.length > 0 ? toolCalls : undefined,
             error,
             conversation: [
                 {
@@ -23250,18 +23256,6 @@ class OpenAiExecutionTools extends OpenAiCompatibleExecutionTools {
     get profile() {
         return OPENAI_PROVIDER_PROFILE;
     }
-    /*
-    Note: Commenting this out to avoid circular dependency
-    /**
-     * Create (sub)tools for calling OpenAI API Assistants
-     *
-     * @param assistantId Which assistant to use
-     * @returns Tools for calling OpenAI API Assistants with same token
-     * /
-    public createAssistantSubtools(assistantId: string_token): OpenAiAssistantExecutionTools {
-        return new OpenAiAssistantExecutionTools({ ...this.options, assistantId });
-    }
-    */
     /**
      * List all available models (non dynamically)
      *
@@ -23296,207 +23290,6 @@ class OpenAiExecutionTools extends OpenAiCompatibleExecutionTools {
     }
 }
 
-/**
- * Execution Tools for calling OpenAI API using the Responses API (Agents)
- *
- * @public exported from `@promptbook/openai`
- */
-class OpenAiAgentExecutionTools extends OpenAiExecutionTools {
-    constructor(options) {
-        super(options);
-        this.vectorStoreId = options.vectorStoreId;
-    }
-    get title() {
-        return 'OpenAI Agent';
-    }
-    get description() {
-        return 'Use OpenAI Responses API (Agentic)';
-    }
-    /**
-     * Calls OpenAI API to use a chat model with streaming.
-     */
-    async callChatModelStream(prompt, onProgress) {
-        if (this.options.isVerbose) {
-            console.info('💬 OpenAI Agent callChatModel call', { prompt });
-        }
-        const { content, parameters, modelRequirements } = prompt;
-        const client = await this.getClient();
-        if (modelRequirements.modelVariant !== 'CHAT') {
-            throw new PipelineExecutionError('Use callChatModel only for CHAT variant');
-        }
-        const rawPromptContent = templateParameters(content, {
-            ...parameters,
-            modelName: 'agent',
-        });
-        // Build input items
-        const input = []; // TODO: Type properly when OpenAI types are updated
-        // Add previous messages from thread (if any)
-        if ('thread' in prompt && Array.isArray(prompt.thread)) {
-            const previousMessages = prompt.thread.map((msg) => ({
-                role: msg.sender === 'assistant' ? 'assistant' : 'user',
-                content: msg.content,
-            }));
-            input.push(...previousMessages);
-        }
-        // Add current user message
-        input.push({
-            role: 'user',
-            content: rawPromptContent,
-        });
-        // Prepare tools
-        const tools = modelRequirements.tools ? mapToolsToOpenAi(modelRequirements.tools) : undefined;
-        // Add file_search if vector store is present
-        const agentTools = tools ? [...tools] : [];
-        let toolResources = undefined;
-        if (this.vectorStoreId) {
-            agentTools.push({ type: 'file_search' });
-            toolResources = {
-                file_search: {
-                    vector_store_ids: [this.vectorStoreId],
-                },
-            };
-        }
-        // Add file_search also if knowledgeSources are present in the prompt (passed via AgentLlmExecutionTools)
-        if (modelRequirements.knowledgeSources &&
-            modelRequirements.knowledgeSources.length > 0 &&
-            !this.vectorStoreId) {
-            // Note: Vector store should have been created by AgentLlmExecutionTools and passed via options.
-            // If we are here, it means we have knowledge sources but no vector store ID.
-            // We can't easily create one here without persisting it.
-            console.warn('Knowledge sources provided but no vector store ID. Creating temporary vector store is not implemented in callChatModelStream.');
-        }
-        const start = $getCurrentDate();
-        // Construct the request
-        const rawRequest = {
-            // TODO: Type properly as OpenAI.Responses.CreateResponseParams
-            model: modelRequirements.modelName || 'gpt-4o',
-            input,
-            instructions: modelRequirements.systemMessage,
-            tools: agentTools.length > 0 ? agentTools : undefined,
-            tool_resources: toolResources,
-            store: false, // Stateless by default as we pass full history
-        };
-        if (this.options.isVerbose) {
-            console.info(colors.bgWhite('rawRequest (Responses API)'), JSON.stringify(rawRequest, null, 4));
-        }
-        // Call Responses API
-        // Note: Using any cast because types might not be updated yet
-        const response = await client.responses.create(rawRequest);
-        if (this.options.isVerbose) {
-            console.info(colors.bgWhite('rawResponse'), JSON.stringify(response, null, 4));
-        }
-        const complete = $getCurrentDate();
-        let resultContent = '';
-        const toolCalls = [];
-        // Parse output items
-        if (response.output) {
-            for (const item of response.output) {
-                if (item.type === 'message' && item.role === 'assistant') {
-                    for (const contentPart of item.content) {
-                        if (contentPart.type === 'output_text') {
-                            // "output_text" based on migration guide, or "text"? Guide says "output_text" in example.
-                            resultContent += contentPart.text;
-                        }
-                        else if (contentPart.type === 'text') {
-                            resultContent += contentPart.text.value || contentPart.text;
-                        }
-                    }
-                }
-                else if (item.type === 'function_call') ;
-            }
-        }
-        // Use output_text helper if available (mentioned in guide)
-        if (response.output_text) {
-            resultContent = response.output_text;
-        }
-        // TODO: Handle tool calls properly (Requires clearer docs or experimentation)
-        onProgress({
-            content: resultContent,
-            modelName: response.model || 'agent',
-            timing: { start, complete },
-            usage: UNCERTAIN_USAGE,
-            rawPromptContent,
-            rawRequest,
-            rawResponse: response,
-        });
-        return exportJson({
-            name: 'promptResult',
-            message: `Result of \`OpenAiAgentExecutionTools.callChatModelStream\``,
-            order: [],
-            value: {
-                content: resultContent,
-                modelName: response.model || 'agent',
-                timing: { start, complete },
-                usage: UNCERTAIN_USAGE,
-                rawPromptContent,
-                rawRequest,
-                rawResponse: response,
-                toolCalls: toolCalls.length > 0 ? toolCalls : undefined,
-            },
-        });
-    }
-    /**
-     * Creates a vector store from knowledge sources
-     */
-    static async createVectorStore(client, name, knowledgeSources) {
-        // Create a vector store
-        const vectorStore = await client.beta.vectorStores.create({
-            name: `${name} Knowledge Base`,
-        });
-        const vectorStoreId = vectorStore.id;
-        // 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 {
-                    // Local files not supported in browser env easily, same as before
-                }
-            }
-            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,
-                });
-            }
-            catch (error) {
-                console.error('Error uploading files to vector store:', error);
-            }
-        }
-        return vectorStoreId;
-    }
-    /**
-     * Discriminant for type guards
-     */
-    get discriminant() {
-        return 'OPEN_AI_AGENT';
-    }
-    /**
-     * Type guard to check if given `LlmExecutionTools` are instanceof `OpenAiAgentExecutionTools`
-     */
-    static isOpenAiAgentExecutionTools(llmExecutionTools) {
-        return llmExecutionTools.discriminant === 'OPEN_AI_AGENT';
-    }
-}
-
 /**
  * Uploads files to OpenAI and returns their IDs
  *
@@ -23518,6 +23311,10 @@ async function uploadFilesToOpenAi(client, files) {
     return fileIds;
 }
 
+const DEFAULT_KNOWLEDGE_SOURCE_DOWNLOAD_TIMEOUT_MS = 30000;
+const DEFAULT_KNOWLEDGE_SOURCE_UPLOAD_TIMEOUT_MS = 900000;
+const VECTOR_STORE_PROGRESS_LOG_INTERVAL_MIN_MS = 15000;
+const VECTOR_STORE_STALL_LOG_THRESHOLD_MS = 30000;
 /**
  * Execution Tools for calling OpenAI API Assistants
  *
@@ -23531,7 +23328,6 @@ async function uploadFilesToOpenAi(client, files) {
  * - `RemoteAgent` - which is an `Agent` that connects to a Promptbook Agents Server
  *
  * @public exported from `@promptbook/openai`
- * @deprecated Use `OpenAiAgentExecutionTools` instead which uses the new OpenAI Responses API
  */
 class OpenAiAssistantExecutionTools extends OpenAiExecutionTools {
     /**
@@ -23968,111 +23764,731 @@ class OpenAiAssistantExecutionTools extends OpenAiExecutionTools {
             assistantId,
         });
     }
-    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;
+    /**
+     * Returns the per-knowledge-source download timeout in milliseconds.
+     */
+    getKnowledgeSourceDownloadTimeoutMs() {
+        var _a;
+        return (_a = this.assistantOptions.knowledgeSourceDownloadTimeoutMs) !== null && _a !== void 0 ? _a : DEFAULT_KNOWLEDGE_SOURCE_DOWNLOAD_TIMEOUT_MS;
+    }
+    /**
+     * Returns the max concurrency for knowledge source uploads.
+     */
+    getKnowledgeSourceUploadMaxConcurrency() {
+        var _a;
+        return (_a = this.assistantOptions.knowledgeSourceUploadMaxConcurrency) !== null && _a !== void 0 ? _a : 5;
+    }
+    /**
+     * Returns the polling interval in milliseconds for vector store uploads.
+     */
+    getKnowledgeSourceUploadPollIntervalMs() {
+        var _a;
+        return (_a = this.assistantOptions.knowledgeSourceUploadPollIntervalMs) !== null && _a !== void 0 ? _a : 5000;
+    }
+    /**
+     * Returns the overall upload timeout in milliseconds for vector store uploads.
+     */
+    getKnowledgeSourceUploadTimeoutMs() {
+        var _a;
+        return (_a = this.assistantOptions.knowledgeSourceUploadTimeoutMs) !== null && _a !== void 0 ? _a : DEFAULT_KNOWLEDGE_SOURCE_UPLOAD_TIMEOUT_MS;
+    }
+    /**
+     * Returns true if we should continue even if vector store ingestion stalls.
+     */
+    shouldContinueOnVectorStoreStall() {
+        var _a;
+        return (_a = this.assistantOptions.shouldContinueOnVectorStoreStall) !== null && _a !== void 0 ? _a : true;
+    }
+    /**
+     * Returns assistant-specific options with extended settings.
+     */
+    get assistantOptions() {
+        return this.options;
+    }
+    /**
+     * Downloads a knowledge source URL into a File for vector store upload.
+     */
+    async downloadKnowledgeSourceFile(options) {
+        var _a;
+        const { source, timeoutMs, logLabel } = options;
+        const startedAtMs = Date.now();
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
         if (this.options.isVerbose) {
-            console.info('[🤰]', 'Starting OpenAI assistant creation', {
-                name,
-                knowledgeSourcesCount,
-                toolsCount,
-                instructionsLength: instructions.length,
+            console.info('[🤰]', 'Downloading knowledge source', {
+                source,
+                timeoutMs,
+                logLabel,
             });
         }
-        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 knowledge sources', {
-                    name,
-                    knowledgeSourcesCount,
+        try {
+            const response = await fetch(source, { signal: controller.signal });
+            const contentType = (_a = response.headers.get('content-type')) !== null && _a !== void 0 ? _a : undefined;
+            if (!response.ok) {
+                console.error('[🤰]', 'Failed to download knowledge source', {
+                    source,
+                    status: response.status,
+                    statusText: response.statusText,
+                    contentType,
+                    elapsedMs: Date.now() - startedAtMs,
+                    logLabel,
                 });
+                return null;
             }
-            // Create a vector store
-            const vectorStore = await client.beta.vectorStores.create({
-                name: `${name} Knowledge Base`,
-            });
-            vectorStoreId = vectorStore.id;
+            const buffer = await response.arrayBuffer();
+            let filename = source.split('/').pop() || 'downloaded-file';
+            try {
+                const url = new URL(source);
+                filename = url.pathname.split('/').pop() || filename;
+            }
+            catch (error) {
+                // Keep default filename
+            }
+            const file = new File([buffer], filename, contentType ? { type: contentType } : undefined);
+            const elapsedMs = Date.now() - startedAtMs;
+            const sizeBytes = buffer.byteLength;
             if (this.options.isVerbose) {
-                console.info('[🤰]', 'Vector store created', {
-                    vectorStoreId,
+                console.info('[🤰]', 'Downloaded knowledge source', {
+                    source,
+                    filename,
+                    sizeBytes,
+                    contentType,
+                    elapsedMs,
+                    logLabel,
                 });
             }
-            // Upload files from knowledge sources to the vector store
-            const fileStreams = [];
-            for (const [index, source] of knowledgeSources.entries()) {
+            return { file, sizeBytes, filename, elapsedMs };
+        }
+        catch (error) {
+            assertsError(error);
+            console.error('[🤰]', 'Error downloading knowledge source', {
+                source,
+                elapsedMs: Date.now() - startedAtMs,
+                logLabel,
+                error: serializeError(error),
+            });
+            return null;
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    /**
+     * Logs vector store file batch diagnostics to help trace ingestion stalls or failures.
+     */
+    async logVectorStoreFileBatchDiagnostics(options) {
+        var _a, _b;
+        const { client, vectorStoreId, batchId, uploadedFiles, logLabel, reason } = options;
+        if (reason === 'stalled' && !this.options.isVerbose) {
+            return;
+        }
+        if (!batchId.startsWith('vsfb_')) {
+            console.error('[🤰]', 'Vector store file batch diagnostics skipped (invalid batch id)', {
+                vectorStoreId,
+                batchId,
+                reason,
+                logLabel,
+            });
+            return;
+        }
+        const fileIdToMetadata = new Map();
+        for (const file of uploadedFiles) {
+            fileIdToMetadata.set(file.fileId, file);
+        }
+        try {
+            const limit = Math.min(100, Math.max(10, uploadedFiles.length));
+            const batchFilesPage = await client.beta.vectorStores.fileBatches.listFiles(vectorStoreId, batchId, {
+                limit,
+            });
+            const batchFiles = (_a = batchFilesPage.data) !== null && _a !== void 0 ? _a : [];
+            const statusCounts = {
+                in_progress: 0,
+                completed: 0,
+                failed: 0,
+                cancelled: 0,
+            };
+            const errorSamples = [];
+            const inProgressSamples = [];
+            const batchFileIds = new Set();
+            for (const file of batchFiles) {
+                batchFileIds.add(file.id);
+                statusCounts[file.status] = ((_b = statusCounts[file.status]) !== null && _b !== void 0 ? _b : 0) + 1;
+                const metadata = fileIdToMetadata.get(file.id);
+                if (file.last_error) {
+                    errorSamples.push({
+                        fileId: file.id,
+                        filename: metadata === null || metadata === void 0 ? void 0 : metadata.filename,
+                        sizeBytes: metadata === null || metadata === void 0 ? void 0 : metadata.sizeBytes,
+                        status: file.status,
+                        lastError: file.last_error,
+                    });
+                }
+                else if (file.status === 'in_progress' && inProgressSamples.length < 5) {
+                    inProgressSamples.push({
+                        fileId: file.id,
+                        filename: metadata === null || metadata === void 0 ? void 0 : metadata.filename,
+                        sizeBytes: metadata === null || metadata === void 0 ? void 0 : metadata.sizeBytes,
+                    });
+                }
+            }
+            const missingSamples = uploadedFiles
+                .filter((file) => !batchFileIds.has(file.fileId))
+                .slice(0, 5)
+                .map((file) => ({
+                fileId: file.fileId,
+                filename: file.filename,
+                sizeBytes: file.sizeBytes,
+            }));
+            const vectorStore = await client.beta.vectorStores.retrieve(vectorStoreId);
+            const logPayload = {
+                vectorStoreId,
+                batchId,
+                reason,
+                vectorStoreStatus: vectorStore.status,
+                vectorStoreFileCounts: vectorStore.file_counts,
+                vectorStoreUsageBytes: vectorStore.usage_bytes,
+                batchFileCount: batchFiles.length,
+                statusCounts,
+                errorSamples: errorSamples.slice(0, 5),
+                inProgressSamples,
+                missingFileCount: uploadedFiles.length - batchFileIds.size,
+                missingSamples,
+                logLabel,
+            };
+            const logFunction = reason === 'stalled' ? console.info : console.error;
+            logFunction('[🤰]', 'Vector store file batch diagnostics', logPayload);
+        }
+        catch (error) {
+            assertsError(error);
+            console.error('[🤰]', 'Vector store file batch diagnostics failed', {
+                vectorStoreId,
+                batchId,
+                reason,
+                logLabel,
+                error: serializeError(error),
+            });
+        }
+    }
+    /**
+     * Uploads knowledge source files to the vector store and polls until processing completes.
+     */
+    async uploadKnowledgeSourceFilesToVectorStore(options) {
+        var _a, _b, _c, _d;
+        const { client, vectorStoreId, files, totalBytes, logLabel } = options;
+        const uploadStartedAtMs = Date.now();
+        const maxConcurrency = Math.max(1, this.getKnowledgeSourceUploadMaxConcurrency());
+        const pollIntervalMs = Math.max(1000, this.getKnowledgeSourceUploadPollIntervalMs());
+        const uploadTimeoutMs = Math.max(1000, this.getKnowledgeSourceUploadTimeoutMs());
+        if (this.options.isVerbose) {
+            console.info('[🤰]', 'Uploading knowledge source files to OpenAI', {
+                vectorStoreId,
+                fileCount: files.length,
+                totalBytes,
+                maxConcurrency,
+                pollIntervalMs,
+                uploadTimeoutMs,
+                logLabel,
+            });
+        }
+        const fileTypeSummary = {};
+        for (const file of files) {
+            const filename = (_a = file.name) !== null && _a !== void 0 ? _a : '';
+            const extension = filename.includes('.')
+                ? (_c = (_b = filename.split('.').pop()) === null || _b === void 0 ? void 0 : _b.toLowerCase()) !== null && _c !== void 0 ? _c : 'unknown'
+                : 'unknown';
+            const sizeBytes = typeof file.size === 'number' ? file.size : 0;
+            const summary = (_d = fileTypeSummary[extension]) !== null && _d !== void 0 ? _d : { count: 0, totalBytes: 0 };
+            summary.count += 1;
+            summary.totalBytes += sizeBytes;
+            fileTypeSummary[extension] = summary;
+        }
+        if (this.options.isVerbose) {
+            console.info('[🤰]', 'Knowledge source file summary', {
+                vectorStoreId,
+                fileCount: files.length,
+                totalBytes,
+                fileTypeSummary,
+                logLabel,
+            });
+        }
+        const fileEntries = files.map((file, index) => ({ file, index }));
+        const fileIterator = fileEntries.values();
+        const fileIds = [];
+        const uploadedFiles = [];
+        const failedUploads = [];
+        let uploadedCount = 0;
+        const processFiles = async (iterator) => {
+            var _a, _b;
+            for (const { file, index } of iterator) {
+                const uploadIndex = index + 1;
+                const filename = file.name || `knowledge-source-${uploadIndex}`;
+                const extension = filename.includes('.')
+                    ? (_b = (_a = filename.split('.').pop()) === null || _a === void 0 ? void 0 : _a.toLowerCase()) !== null && _b !== void 0 ? _b : 'unknown'
+                    : 'unknown';
+                const sizeBytes = typeof file.size === 'number' ? file.size : undefined;
+                const fileUploadStartedAtMs = Date.now();
+                if (this.options.isVerbose) {
+                    console.info('[🤰]', 'Uploading knowledge source file', {
+                        index: uploadIndex,
+                        total: files.length,
+                        filename,
+                        extension,
+                        sizeBytes,
+                        logLabel,
+                    });
+                }
                 try {
+                    const uploaded = await client.files.create({ file, purpose: 'assistants' });
+                    fileIds.push(uploaded.id);
+                    uploadedFiles.push({ fileId: uploaded.id, filename, sizeBytes });
+                    uploadedCount += 1;
                     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',
+                        console.info('[🤰]', 'Uploaded knowledge source file', {
+                            index: uploadIndex,
+                            total: files.length,
+                            filename,
+                            sizeBytes,
+                            fileId: uploaded.id,
+                            elapsedMs: Date.now() - fileUploadStartedAtMs,
+                            logLabel,
                         });
                     }
-                    // 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();
-                        let filename = source.split('/').pop() || 'downloaded-file';
-                        try {
-                            const url = new URL(source);
-                            filename = url.pathname.split('/').pop() || filename;
-                        }
-                        catch (error) {
-                            // Keep default filename
-                        }
-                        const blob = new Blob([buffer]);
-                        const file = new File([blob], filename);
-                        fileStreams.push(file);
-                    }
-                    else {
-                        /*
-                        TODO: [🐱‍🚀] Resolve problem with browser environment
-                        // 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);
+                    assertsError(error);
+                    const serializedError = serializeError(error);
+                    failedUploads.push({ index: uploadIndex, filename, error: serializedError });
+                    console.error('[🤰]', 'Failed to upload knowledge source file', {
+                        index: uploadIndex,
+                        total: files.length,
+                        filename,
+                        sizeBytes,
+                        elapsedMs: Date.now() - fileUploadStartedAtMs,
+                        logLabel,
+                        error: serializedError,
+                    });
                 }
             }
-            // Batch upload files to the vector store
-            if (fileStreams.length > 0) {
-                try {
-                    await client.beta.vectorStores.fileBatches.uploadAndPoll(vectorStoreId, {
-                        files: fileStreams,
+        };
+        const workerCount = Math.min(maxConcurrency, files.length);
+        const workers = Array.from({ length: workerCount }, () => processFiles(fileIterator));
+        await Promise.all(workers);
+        if (this.options.isVerbose) {
+            console.info('[🤰]', 'Finished uploading knowledge source files', {
+                vectorStoreId,
+                fileCount: files.length,
+                uploadedCount,
+                failedCount: failedUploads.length,
+                elapsedMs: Date.now() - uploadStartedAtMs,
+                failedSamples: failedUploads.slice(0, 3),
+                logLabel,
+            });
+        }
+        if (fileIds.length === 0) {
+            console.error('[🤰]', 'No knowledge source files were uploaded', {
+                vectorStoreId,
+                fileCount: files.length,
+                failedCount: failedUploads.length,
+                logLabel,
+            });
+            return null;
+        }
+        const batch = await client.beta.vectorStores.fileBatches.create(vectorStoreId, {
+            file_ids: fileIds,
+        });
+        const expectedBatchId = batch.id;
+        const expectedBatchIdValid = expectedBatchId.startsWith('vsfb_');
+        if (!expectedBatchIdValid) {
+            console.error('[🤰]', 'Vector store file batch id looks invalid', {
+                vectorStoreId,
+                batchId: expectedBatchId,
+                batchVectorStoreId: batch.vector_store_id,
+                logLabel,
+            });
+        }
+        else if (batch.vector_store_id !== vectorStoreId) {
+            console.error('[🤰]', 'Vector store file batch vector store id mismatch', {
+                vectorStoreId,
+                batchId: expectedBatchId,
+                batchVectorStoreId: batch.vector_store_id,
+                logLabel,
+            });
+        }
+        if (this.options.isVerbose) {
+            console.info('[🤰]', 'Created vector store file batch', {
+                vectorStoreId,
+                batchId: expectedBatchId,
+                fileCount: fileIds.length,
+                logLabel,
+            });
+        }
+        const pollStartedAtMs = Date.now();
+        const progressLogIntervalMs = Math.max(VECTOR_STORE_PROGRESS_LOG_INTERVAL_MIN_MS, pollIntervalMs);
+        const diagnosticsIntervalMs = Math.max(60000, pollIntervalMs * 5);
+        let lastStatus;
+        let lastCountsKey = '';
+        let lastProgressKey = '';
+        let lastLogAtMs = 0;
+        let lastProgressAtMs = pollStartedAtMs;
+        let lastDiagnosticsAtMs = pollStartedAtMs;
+        let latestBatch = batch;
+        let loggedBatchIdMismatch = false;
+        let shouldPoll = true;
+        while (shouldPoll) {
+            latestBatch = await client.beta.vectorStores.fileBatches.retrieve(vectorStoreId, expectedBatchId);
+            const counts = latestBatch.file_counts;
+            const countsKey = `${counts.completed}/${counts.failed}/${counts.in_progress}/${counts.cancelled}/${counts.total}`;
+            const nowMs = Date.now();
+            const returnedBatchId = latestBatch.id;
+            // [🤰] Note: Sometimes OpenAI returns Vector Store object instead of Batch object, or IDs get swapped.
+            // We only consider it a mismatch if the returned ID looks like a Batch ID.
+            const batchIdMismatch = returnedBatchId !== expectedBatchId && returnedBatchId.startsWith('vsfb_');
+            const diagnosticsBatchId = batchIdMismatch && returnedBatchId.startsWith('vsfb_') ? returnedBatchId : expectedBatchId;
+            const shouldLog = this.options.isVerbose &&
+                (latestBatch.status !== lastStatus ||
+                    countsKey !== lastCountsKey ||
+                    nowMs - lastLogAtMs >= progressLogIntervalMs);
+            if (batchIdMismatch && !loggedBatchIdMismatch) {
+                console.error('[🤰]', 'Vector store file batch id mismatch', {
+                    vectorStoreId,
+                    expectedBatchId,
+                    returnedBatchId,
+                    status: latestBatch.status,
+                    fileCounts: counts,
+                    logLabel,
+                });
+                loggedBatchIdMismatch = true;
+            }
+            if (countsKey !== lastProgressKey) {
+                lastProgressKey = countsKey;
+                lastProgressAtMs = nowMs;
+            }
+            if (shouldLog) {
+                console.info('[🤰]', 'Vector store file batch status', {
+                    vectorStoreId,
+                    batchId: expectedBatchId,
+                    ...(batchIdMismatch ? { returnedBatchId } : {}),
+                    status: latestBatch.status,
+                    fileCounts: counts,
+                    elapsedMs: nowMs - pollStartedAtMs,
+                    logLabel,
+                });
+                // [🤰] If there are in-progress files for a long time, log their details
+                if (counts.in_progress > 0 && nowMs - lastProgressAtMs > VECTOR_STORE_STALL_LOG_THRESHOLD_MS) {
+                    await this.logVectorStoreFileBatchDiagnostics({
+                        client,
+                        vectorStoreId,
+                        batchId: diagnosticsBatchId,
+                        uploadedFiles,
+                        logLabel,
+                        reason: 'stalled',
+                    });
+                }
+                lastStatus = latestBatch.status;
+                lastCountsKey = countsKey;
+                lastLogAtMs = nowMs;
+            }
+            if (nowMs - lastProgressAtMs >= diagnosticsIntervalMs &&
+                nowMs - lastDiagnosticsAtMs >= diagnosticsIntervalMs) {
+                lastDiagnosticsAtMs = nowMs;
+                await this.logVectorStoreFileBatchDiagnostics({
+                    client,
+                    vectorStoreId,
+                    batchId: diagnosticsBatchId,
+                    uploadedFiles,
+                    logLabel,
+                    reason: 'stalled',
+                });
+            }
+            if (latestBatch.status === 'completed') {
+                if (this.options.isVerbose) {
+                    console.info('[🤰]', 'Vector store file batch completed', {
+                        vectorStoreId,
+                        batchId: expectedBatchId,
+                        ...(batchIdMismatch ? { returnedBatchId } : {}),
+                        fileCounts: latestBatch.file_counts,
+                        elapsedMs: Date.now() - uploadStartedAtMs,
+                        logLabel,
                     });
+                }
+                if (latestBatch.file_counts.failed > 0) {
+                    console.error('[🤰]', 'Vector store file batch completed with failures', {
+                        vectorStoreId,
+                        batchId: expectedBatchId,
+                        ...(batchIdMismatch ? { returnedBatchId } : {}),
+                        fileCounts: latestBatch.file_counts,
+                        logLabel,
+                    });
+                    await this.logVectorStoreFileBatchDiagnostics({
+                        client,
+                        vectorStoreId,
+                        batchId: diagnosticsBatchId,
+                        uploadedFiles,
+                        logLabel,
+                        reason: 'failed',
+                    });
+                }
+                shouldPoll = false;
+                continue;
+            }
+            if (latestBatch.status === 'failed' || latestBatch.status === 'cancelled') {
+                console.error('[🤰]', 'Vector store file batch did not complete', {
+                    vectorStoreId,
+                    batchId: expectedBatchId,
+                    ...(batchIdMismatch ? { returnedBatchId } : {}),
+                    status: latestBatch.status,
+                    fileCounts: latestBatch.file_counts,
+                    elapsedMs: Date.now() - uploadStartedAtMs,
+                    logLabel,
+                });
+                await this.logVectorStoreFileBatchDiagnostics({
+                    client,
+                    vectorStoreId,
+                    batchId: diagnosticsBatchId,
+                    uploadedFiles,
+                    logLabel,
+                    reason: 'failed',
+                });
+                shouldPoll = false;
+                continue;
+            }
+            if (nowMs - pollStartedAtMs >= uploadTimeoutMs) {
+                console.error('[🤰]', 'Timed out waiting for vector store file batch', {
+                    vectorStoreId,
+                    batchId: expectedBatchId,
+                    ...(batchIdMismatch ? { returnedBatchId } : {}),
+                    fileCounts: latestBatch.file_counts,
+                    elapsedMs: nowMs - pollStartedAtMs,
+                    uploadTimeoutMs,
+                    logLabel,
+                });
+                await this.logVectorStoreFileBatchDiagnostics({
+                    client,
+                    vectorStoreId,
+                    batchId: diagnosticsBatchId,
+                    uploadedFiles,
+                    logLabel,
+                    reason: 'timeout',
+                });
+                if (this.shouldContinueOnVectorStoreStall()) {
+                    console.warn('[🤰]', 'Continuing despite vector store timeout as requested', {
+                        vectorStoreId,
+                        logLabel,
+                    });
+                    shouldPoll = false;
+                    continue;
+                }
+                try {
+                    const cancelBatchId = batchIdMismatch && returnedBatchId.startsWith('vsfb_') ? returnedBatchId : expectedBatchId;
+                    if (!cancelBatchId.startsWith('vsfb_')) {
+                        console.error('[🤰]', 'Skipping vector store file batch cancel (invalid batch id)', {
+                            vectorStoreId,
+                            batchId: cancelBatchId,
+                            logLabel,
+                        });
+                    }
+                    else {
+                        await client.beta.vectorStores.fileBatches.cancel(vectorStoreId, cancelBatchId);
+                    }
                     if (this.options.isVerbose) {
-                        console.info('[🤰]', 'Uploaded files to vector store', {
+                        console.info('[🤰]', 'Cancelled vector store file batch after timeout', {
                             vectorStoreId,
-                            fileCount: fileStreams.length,
+                            batchId: batchIdMismatch && returnedBatchId.startsWith('vsfb_')
+                                ? returnedBatchId
+                                : expectedBatchId,
+                            ...(batchIdMismatch ? { returnedBatchId } : {}),
+                            logLabel,
                         });
                     }
                 }
                 catch (error) {
-                    console.error('Error uploading files to vector store:', error);
+                    assertsError(error);
+                    console.error('[🤰]', 'Failed to cancel vector store file batch after timeout', {
+                        vectorStoreId,
+                        batchId: expectedBatchId,
+                        ...(batchIdMismatch ? { returnedBatchId } : {}),
+                        logLabel,
+                        error: serializeError(error),
+                    });
+                }
+                shouldPoll = false;
+                continue;
+            }
+            await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+        }
+        return latestBatch;
+    }
+    /**
+     * Creates a vector store and uploads knowledge sources, returning its ID.
+     */
+    async createVectorStoreWithKnowledgeSources(options) {
+        const { client, name, knowledgeSources, logLabel } = options;
+        const knowledgeSourcesCount = knowledgeSources.length;
+        const downloadTimeoutMs = this.getKnowledgeSourceDownloadTimeoutMs();
+        if (this.options.isVerbose) {
+            console.info('[🤰]', 'Creating vector store with knowledge sources', {
+                name,
+                knowledgeSourcesCount,
+                downloadTimeoutMs,
+                logLabel,
+            });
+        }
+        const vectorStore = await client.beta.vectorStores.create({
+            name: `${name} Knowledge Base`,
+        });
+        const vectorStoreId = vectorStore.id;
+        if (this.options.isVerbose) {
+            console.info('[🤰]', 'Vector store created', {
+                vectorStoreId,
+                logLabel,
+            });
+        }
+        const fileStreams = [];
+        const skippedSources = [];
+        let totalBytes = 0;
+        const processingStartedAtMs = Date.now();
+        for (const [index, source] of knowledgeSources.entries()) {
+            try {
+                const sourceType = source.startsWith('http') || source.startsWith('https') ? 'url' : 'file';
+                if (this.options.isVerbose) {
+                    console.info('[🤰]', 'Processing knowledge source', {
+                        index: index + 1,
+                        total: knowledgeSourcesCount,
+                        source,
+                        sourceType,
+                        logLabel,
+                    });
+                }
+                // Check if it's a URL
+                if (source.startsWith('http://') || source.startsWith('https://')) {
+                    const downloadResult = await this.downloadKnowledgeSourceFile({
+                        source,
+                        timeoutMs: downloadTimeoutMs,
+                        logLabel,
+                    });
+                    if (downloadResult) {
+                        fileStreams.push(downloadResult.file);
+                        totalBytes += downloadResult.sizeBytes;
+                    }
+                    else {
+                        skippedSources.push({ source, reason: 'download_failed' });
+                    }
                 }
+                else {
+                    skippedSources.push({ source, reason: 'unsupported_source_type' });
+                    if (this.options.isVerbose) {
+                        console.info('[🤰]', 'Skipping knowledge source (unsupported type)', {
+                            source,
+                            sourceType,
+                            logLabel,
+                        });
+                    }
+                    /*
+                    TODO: [?????] Resolve problem with browser environment
+                    // 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) {
+                assertsError(error);
+                skippedSources.push({ source, reason: 'processing_error' });
+                console.error('[🤰]', 'Error processing knowledge source', {
+                    source,
+                    logLabel,
+                    error: serializeError(error),
+                });
             }
         }
+        if (this.options.isVerbose) {
+            console.info('[🤰]', 'Finished processing knowledge sources', {
+                total: knowledgeSourcesCount,
+                downloadedCount: fileStreams.length,
+                skippedCount: skippedSources.length,
+                totalBytes,
+                elapsedMs: Date.now() - processingStartedAtMs,
+                skippedSamples: skippedSources.slice(0, 3),
+                logLabel,
+            });
+        }
+        if (fileStreams.length > 0) {
+            if (this.options.isVerbose) {
+                console.info('[🤰]', 'Uploading files to vector store', {
+                    vectorStoreId,
+                    fileCount: fileStreams.length,
+                    totalBytes,
+                    maxConcurrency: this.getKnowledgeSourceUploadMaxConcurrency(),
+                    pollIntervalMs: this.getKnowledgeSourceUploadPollIntervalMs(),
+                    uploadTimeoutMs: this.getKnowledgeSourceUploadTimeoutMs(),
+                    logLabel,
+                });
+            }
+            try {
+                await this.uploadKnowledgeSourceFilesToVectorStore({
+                    client,
+                    vectorStoreId,
+                    files: fileStreams,
+                    totalBytes,
+                    logLabel,
+                });
+            }
+            catch (error) {
+                assertsError(error);
+                console.error('[🤰]', 'Error uploading files to vector store', {
+                    vectorStoreId,
+                    logLabel,
+                    error: serializeError(error),
+                });
+            }
+        }
+        else if (this.options.isVerbose) {
+            console.info('[🤰]', 'No knowledge source files to upload', {
+                vectorStoreId,
+                skippedCount: skippedSources.length,
+                logLabel,
+            });
+        }
+        return {
+            vectorStoreId,
+            uploadedFileCount: fileStreams.length,
+            skippedCount: skippedSources.length,
+            totalBytes,
+        };
+    }
+    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) {
+            const vectorStoreResult = await this.createVectorStoreWithKnowledgeSources({
+                client,
+                name,
+                knowledgeSources,
+                logLabel: 'assistant creation',
+            });
+            vectorStoreId = vectorStoreResult.vectorStoreId;
+        }
         // Create assistant with vector store attached
         const assistantConfig = {
             name,
@@ -24138,91 +24554,14 @@ class OpenAiAssistantExecutionTools extends OpenAiExecutionTools {
         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 assistant update', {
-                    assistantId,
-                    name,
-                    knowledgeSourcesCount,
-                });
-            }
-            // Create a vector store
-            const vectorStore = await client.beta.vectorStores.create({
-                name: `${name} Knowledge Base`,
+            const vectorStoreResult = await this.createVectorStoreWithKnowledgeSources({
+                client,
+                name: name !== null && name !== void 0 ? name : assistantId,
+                knowledgeSources,
+                logLabel: 'assistant update',
             });
-            vectorStoreId = vectorStore.id;
-            if (this.options.isVerbose) {
-                console.info('[🤰]', 'Vector store created for assistant update', {
-                    vectorStoreId,
-                });
-            }
-            // Upload files from knowledge sources to the vector store
-            const fileStreams = [];
-            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
-                        const response = await fetch(source);
-                        if (!response.ok) {
-                            console.error(`Failed to download ${source}: ${response.statusText}`);
-                            continue;
-                        }
-                        const buffer = await response.arrayBuffer();
-                        let filename = source.split('/').pop() || 'downloaded-file';
-                        try {
-                            const url = new URL(source);
-                            filename = url.pathname.split('/').pop() || filename;
-                        }
-                        catch (error) {
-                            // Keep default filename
-                        }
-                        const blob = new Blob([buffer]);
-                        const file = new File([blob], filename);
-                        fileStreams.push(file);
-                    }
-                    else {
-                        /*
-                        TODO: [🐱‍🚀] Resolve problem with browser environment
-                        // 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 files to vector store for update', {
-                            vectorStoreId,
-                            fileCount: fileStreams.length,
-                        });
-                    }
-                }
-                catch (error) {
-                    console.error('Error uploading files to vector store:', error);
-                }
-            }
+            vectorStoreId = vectorStoreResult.vectorStoreId;
         }
         const assistantUpdate = {
             name,
@@ -24326,7 +24665,6 @@ function emitAssistantPreparationProgress(options) {
  * - `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
- * - `OpenAiAgentExecutionTools` - which is a specific implementation of `LlmExecutionTools` for OpenAI models with agent capabilities (using Responses API), recommended for usage in `Agent` or `AgentLlmExecutionTools`
  * - `OpenAiAssistantExecutionTools` - (Deprecated) which is a specific implementation of `LlmExecutionTools` for OpenAI models with assistant capabilities
  * - `RemoteAgent` - which is an `Agent` that connects to a Promptbook Agents Server
  *
@@ -24489,70 +24827,25 @@ class AgentLlmExecutionTools {
             }, // Cast to avoid readonly mismatch from spread
         };
         console.log('!!!! promptWithAgentModelRequirements:', promptWithAgentModelRequirements);
-        if (OpenAiAgentExecutionTools.isOpenAiAgentExecutionTools(this.options.llmTools)) {
+        if (OpenAiAssistantExecutionTools.isOpenAiAssistantExecutionTools(this.options.llmTools)) {
+            // ... deprecated path ...
             const requirementsHash = SHA256(JSON.stringify(modelRequirements)).toString();
-            const cached = AgentLlmExecutionTools.vectorStoreCache.get(this.title);
-            let agentTools;
-            if (cached && cached.requirementsHash === requirementsHash) {
-                if (this.options.isVerbose) {
-                    console.log(`1️⃣ Using cached OpenAI Agent Vector Store for agent ${this.title}...`);
-                }
-                // Create new instance with cached vectorStoreId
-                // We need to access options from the original tool.
-                // We assume isOpenAiAgentExecutionTools implies it has options we can clone.
-                // But protected options are not accessible.
-                // We can cast to access options if they were public, or use a method to clone.
-                // OpenAiAgentExecutionTools doesn't have a clone method.
-                // However, we can just assume the passed tool *might* not have the vector store yet, or we are replacing it.
-                // Actually, if the passed tool IS OpenAiAgentExecutionTools, we should use it as a base.
-                // TODO: [🧠] This is a bit hacky, accessing protected options or recreating tools.
-                // Ideally OpenAiAgentExecutionTools should have a method `withVectorStoreId`.
-                agentTools = new OpenAiAgentExecutionTools({
-                    ...this.options.llmTools.options,
-                    vectorStoreId: cached.vectorStoreId,
-                });
-            }
-            else {
+            const cached = AgentLlmExecutionTools.assistantCache.get(this.title);
+            let assistant;
+            if (this.options.assistantPreparationMode === 'external') {
+                assistant = this.options.llmTools;
                 if (this.options.isVerbose) {
-                    console.log(`1️⃣ Creating/Updating OpenAI Agent Vector Store for agent ${this.title}...`);
-                }
-                let vectorStoreId;
-                if (modelRequirements.knowledgeSources && modelRequirements.knowledgeSources.length > 0) {
-                    const client = await this.options.llmTools.getClient();
-                    vectorStoreId = await OpenAiAgentExecutionTools.createVectorStore(client, this.title, modelRequirements.knowledgeSources);
-                }
-                if (vectorStoreId) {
-                    AgentLlmExecutionTools.vectorStoreCache.set(this.title, {
-                        vectorStoreId,
-                        requirementsHash,
+                    console.info('[🤰]', 'Using externally managed OpenAI Assistant', {
+                        agent: this.title,
+                        assistantId: assistant.assistantId,
                     });
                 }
-                agentTools = new OpenAiAgentExecutionTools({
-                    ...this.options.llmTools.options,
-                    vectorStoreId,
+                AgentLlmExecutionTools.assistantCache.set(this.title, {
+                    assistantId: assistant.assistantId,
+                    requirementsHash,
                 });
             }
-            // Create modified chat prompt with agent system message specific to OpenAI Agent
-            // Note: Unlike Assistants API, Responses API expects instructions (system message) to be passed in the call.
-            // So we use promptWithAgentModelRequirements which has the system message prepended.
-            // But we need to make sure we pass knowledgeSources in modelRequirements so OpenAiAgentExecutionTools can fallback to warning if vectorStoreId is missing (though we just handled it).
-            const promptForAgent = {
-                ...promptWithAgentModelRequirements,
-                modelRequirements: {
-                    ...promptWithAgentModelRequirements.modelRequirements,
-                    knowledgeSources: modelRequirements.knowledgeSources
-                        ? [...modelRequirements.knowledgeSources]
-                        : undefined, // Pass knowledge sources explicitly
-                },
-            };
-            underlyingLlmResult = await agentTools.callChatModelStream(promptForAgent, onProgress);
-        }
-        else if (OpenAiAssistantExecutionTools.isOpenAiAssistantExecutionTools(this.options.llmTools)) {
-            // ... deprecated path ...
-            const requirementsHash = SHA256(JSON.stringify(modelRequirements)).toString();
-            const cached = AgentLlmExecutionTools.assistantCache.get(this.title);
-            let assistant;
-            if (cached) {
+            else if (cached) {
                 if (cached.requirementsHash === requirementsHash) {
                     if (this.options.isVerbose) {
                         console.info('[🤰]', 'Using cached OpenAI Assistant', {
@@ -24618,11 +24911,6 @@ class AgentLlmExecutionTools {
                     requirementsHash,
                 });
             }
-            // [0] Expose prepared externals
-            if (this.preparedExternals) {
-                this /* <- TODO: !!!!!! Remove */.preparedExternals.openaiAssistantId =
-                    assistant.assistantId;
-            }
             // Create modified chat prompt with agent system message specific to OpenAI Assistant
             const promptWithAgentModelRequirementsForOpenAiAssistantExecutionTools = {
                 ...promptWithAgentModelRequirements,
@@ -24744,7 +25032,6 @@ function buildTeacherSummary(commitments, used) {
  * - `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
- * - `OpenAiAgentExecutionTools` - which is a specific implementation of `LlmExecutionTools` for OpenAI models with agent capabilities (using Responses API), recommended for usage in `Agent` or `AgentLlmExecutionTools`
  * - `OpenAiAssistantExecutionTools` - (Deprecated) which is a specific implementation of `LlmExecutionTools` for OpenAI models with assistant capabilities
  * - `RemoteAgent` - which is an `Agent` that connects to a Promptbook Agents Server
  *
@@ -24776,6 +25063,7 @@ class Agent extends AgentLlmExecutionTools {
         super({
             isVerbose: options.isVerbose,
             llmTools: getSingleLlmExecutionTools(options.executionTools.llm),
+            assistantPreparationMode: options.assistantPreparationMode,
             agentSource: agentSource.value, // <- TODO: [🐱‍🚀] Allow to pass BehaviorSubject<string_book> OR refresh llmExecutionTools.callChat on agentSource change
         });
         _Agent_instances.add(this);
@@ -24815,10 +25103,6 @@ class Agent extends AgentLlmExecutionTools {
          * Human-readable titles for tool functions
          */
         this.toolTitles = {};
-        /**
-         * Externals prepared for the agent, like OpenAI assistant, etc.
-         */
-        this.preparedExternals = {};
         // TODO: [🐱‍🚀] Add `Agent` simple "mocked" learning by appending to agent source
         // TODO: [🐱‍🚀] Add `Agent` learning by promptbookAgent
         this.teacherAgent = options.teacherAgent;
@@ -25055,6 +25339,63 @@ async function _Agent_selfLearnTeacher(prompt, result) {
  * TODO: [🧠][😰]Agent is not working with the parameters, should it be?
  */
 
+/**
+ * Resolve a remote META IMAGE value into an absolute URL when possible.
+ */
+function resolveRemoteImageUrl(imageUrl, agentUrl) {
+    if (!imageUrl) {
+        return undefined;
+    }
+    if (imageUrl.startsWith('http://') ||
+        imageUrl.startsWith('https://') ||
+        imageUrl.startsWith('data:') ||
+        imageUrl.startsWith('blob:')) {
+        return imageUrl;
+    }
+    try {
+        return new URL(imageUrl, agentUrl).href;
+    }
+    catch (_a) {
+        return imageUrl;
+    }
+}
+/**
+ * Format a META commitment line when the value is provided.
+ */
+function formatMetaLine(label, value) {
+    if (!value) {
+        return null;
+    }
+    return `META ${label} ${value}`;
+}
+/**
+ * Build a minimal agent source snapshot for remote agents.
+ */
+function buildRemoteAgentSource(profile, meta) {
+    const metaLines = [
+        formatMetaLine('FULLNAME', meta === null || meta === void 0 ? void 0 : meta.fullname),
+        formatMetaLine('IMAGE', meta === null || meta === void 0 ? void 0 : meta.image),
+        formatMetaLine('DESCRIPTION', meta === null || meta === void 0 ? void 0 : meta.description),
+        formatMetaLine('COLOR', meta === null || meta === void 0 ? void 0 : meta.color),
+        formatMetaLine('FONT', meta === null || meta === void 0 ? void 0 : meta.font),
+        formatMetaLine('LINK', meta === null || meta === void 0 ? void 0 : meta.link),
+    ]
+        .filter((line) => Boolean(line))
+        .join('\n');
+    const personaBlock = profile.personaDescription
+        ? spaceTrim$2((block) => `
+            PERSONA
+            ${block(profile.personaDescription || '')}
+        `)
+        : '';
+    return book `
+        ${profile.agentName}
+
+        ${metaLines}
+
+        ${personaBlock}
+    `;
+}
 /**
  * Represents one AI Agent
  *
@@ -25069,6 +25410,7 @@ async function _Agent_selfLearnTeacher(prompt, result) {
  */
 class RemoteAgent extends Agent {
     static async connect(options) {
+        var _a, _b, _c;
         const agentProfileUrl = `${options.agentUrl}/api/profile`;
         const profileResponse = await fetch(agentProfileUrl);
         // <- TODO: [🐱‍🚀] What about closed-source agents?
@@ -25088,14 +25430,14 @@ class RemoteAgent extends Agent {
                 
                 `));
         }
-        const profile = await profileResponse.json();
+        const profile = (await profileResponse.json());
+        const resolvedMeta = {
+            ...(profile.meta || {}),
+            image: resolveRemoteImageUrl((_a = profile.meta) === null || _a === void 0 ? void 0 : _a.image, options.agentUrl),
+        };
         // Note: We are creating dummy agent source because we don't have the source from the remote agent
         //       But we populate the metadata from the profile
-        const agentSource = new BehaviorSubject(book `
-            ${profile.agentName}
-
-            ${profile.personaDescription}
-        `);
+        const agentSource = new BehaviorSubject(buildRemoteAgentSource(profile, resolvedMeta));
         // <- TODO: [🐱‍🚀] createBookFromProfile
         // <- TODO: [🐱‍🚀] Support updating and self-updating
         const remoteAgent = new RemoteAgent({
@@ -25118,10 +25460,10 @@ class RemoteAgent extends Agent {
         });
         remoteAgent._remoteAgentName = profile.agentName;
         remoteAgent._remoteAgentHash = profile.agentHash;
-        remoteAgent.personaDescription = profile.personaDescription;
-        remoteAgent.initialMessage = profile.initialMessage;
-        remoteAgent.links = profile.links;
-        remoteAgent.meta = profile.meta;
+        remoteAgent.personaDescription = (_b = profile.personaDescription) !== null && _b !== void 0 ? _b : null;
+        remoteAgent.initialMessage = (_c = profile.initialMessage) !== null && _c !== void 0 ? _c : null;
+        remoteAgent.links = profile.links || [];
+        remoteAgent.meta = resolvedMeta;
         remoteAgent.capabilities = profile.capabilities || [];
         remoteAgent.samples = profile.samples || [];
         remoteAgent.toolTitles = profile.toolTitles || {};