@promptbook/node 0.110.0-1 → 0.110.0-10

package/umd/index.umd.js

@@ -1,8 +1,8 @@
 (function (global, factory) {
-    typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports, require('colors'), require('fs/promises'), require('path'), require('spacetrim'), require('jszip'), require('crypto'), require('crypto-js'), require('crypto-js/enc-hex'), require('@mozilla/readability'), require('jsdom'), require('showdown'), require('child_process'), require('waitasecond'), require('dotenv'), require('crypto-js/sha256'), require('rxjs'), require('moment'), require('mime-types'), require('papaparse'), require('bottleneck'), require('openai')) :
-    typeof define === 'function' && define.amd ? define(['exports', 'colors', 'fs/promises', 'path', 'spacetrim', 'jszip', 'crypto', 'crypto-js', 'crypto-js/enc-hex', '@mozilla/readability', 'jsdom', 'showdown', 'child_process', 'waitasecond', 'dotenv', 'crypto-js/sha256', 'rxjs', 'moment', 'mime-types', 'papaparse', 'bottleneck', 'openai'], factory) :
-    (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global["promptbook-node"] = {}, global.colors, global.promises, global.path, global.spaceTrim$1, global.JSZip, global.crypto, global.cryptoJs, global.hexEncoder, global.readability, global.jsdom, global.showdown, global.child_process, global.waitasecond, global.dotenv, global.sha256, global.rxjs, global.moment, global.mimeTypes, global.papaparse, global.Bottleneck, global.OpenAI));
-})(this, (function (exports, colors, promises, path, spaceTrim$1, JSZip, crypto, cryptoJs, hexEncoder, readability, jsdom, showdown, child_process, waitasecond, dotenv, sha256, rxjs, moment, mimeTypes, papaparse, Bottleneck, OpenAI) { 'use strict';
+    typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports, require('colors'), require('fs/promises'), require('path'), require('spacetrim'), require('jszip'), require('crypto'), require('crypto-js'), require('crypto-js/enc-hex'), require('@mozilla/readability'), require('jsdom'), require('showdown'), require('child_process'), require('waitasecond'), require('dotenv'), require('crypto-js/sha256'), require('rxjs'), require('moment'), require('mime-types'), require('papaparse'), require('@openai/agents'), require('bottleneck'), require('openai')) :
+    typeof define === 'function' && define.amd ? define(['exports', 'colors', 'fs/promises', 'path', 'spacetrim', 'jszip', 'crypto', 'crypto-js', 'crypto-js/enc-hex', '@mozilla/readability', 'jsdom', 'showdown', 'child_process', 'waitasecond', 'dotenv', 'crypto-js/sha256', 'rxjs', 'moment', 'mime-types', 'papaparse', '@openai/agents', 'bottleneck', 'openai'], factory) :
+    (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global["promptbook-node"] = {}, global.colors, global.promises, global.path, global.spaceTrim$1, global.JSZip, global.crypto, global.cryptoJs, global.hexEncoder, global.readability, global.jsdom, global.showdown, global.child_process, global.waitasecond, global.dotenv, global.sha256, global.rxjs, global.moment, global.mimeTypes, global.papaparse, global.agents, global.Bottleneck, global.OpenAI));
+})(this, (function (exports, colors, promises, path, spaceTrim$1, JSZip, crypto, cryptoJs, hexEncoder, readability, jsdom, showdown, child_process, waitasecond, dotenv, sha256, rxjs, moment, mimeTypes, papaparse, agents, Bottleneck, OpenAI) { 'use strict';
 
     function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
 
@@ -48,7 +48,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.110.0-1';
+    const PROMPTBOOK_ENGINE_VERSION = '0.110.0-10';
     /**
      * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
      * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -13723,6 +13723,28 @@
                 return currentMessage + separator + content;
             });
         }
+        /**
+         * Helper method to create a new requirements object with updated prompt suffix
+         */
+        updatePromptSuffix(requirements, contentUpdate) {
+            const newSuffix = typeof contentUpdate === 'string' ? contentUpdate : contentUpdate(requirements.promptSuffix);
+            return {
+                ...requirements,
+                promptSuffix: newSuffix,
+            };
+        }
+        /**
+         * Helper method to append content to the prompt suffix
+         * Default separator is a single newline for bullet lists.
+         */
+        appendToPromptSuffix(requirements, content, separator = '\n') {
+            return this.updatePromptSuffix(requirements, (currentSuffix) => {
+                if (!currentSuffix.trim()) {
+                    return content;
+                }
+                return `${currentSuffix}${separator}${content}`;
+            });
+        }
         /**
          * Helper method to add a comment section to the system message
          * Comments are lines starting with # that will be removed from the final system message
@@ -13900,13 +13922,9 @@
         `);
         }
         applyToAgentModelRequirements(requirements, _content) {
-            const updatedMetadata = {
-                ...requirements.metadata,
-                isClosed: true,
-            };
             return {
                 ...requirements,
-                metadata: updatedMetadata,
+                isClosed: true,
             };
         }
     }
@@ -14184,12 +14202,12 @@
                 return requirements;
             }
             // Get existing dictionary entries from metadata
-            const existingDictionary = ((_a = requirements.metadata) === null || _a === void 0 ? void 0 : _a.DICTIONARY) || '';
+            const existingDictionary = ((_a = requirements._metadata) === null || _a === void 0 ? void 0 : _a.DICTIONARY) || '';
             // Merge the new dictionary entry with existing entries
             const mergedDictionary = existingDictionary ? `${existingDictionary}\n${trimmedContent}` : trimmedContent;
             // Store the merged dictionary in metadata for debugging and inspection
             const updatedMetadata = {
-                ...requirements.metadata,
+                ...requirements._metadata,
                 DICTIONARY: mergedDictionary,
             };
             // Create the dictionary section for the system message
@@ -14197,7 +14215,7 @@
             const dictionarySection = `# DICTIONARY\n${mergedDictionary}`;
             return {
                 ...this.appendToSystemMessage(requirements, dictionarySection),
-                metadata: updatedMetadata,
+                _metadata: updatedMetadata,
             };
         }
     }
@@ -14337,10 +14355,7 @@
         applyToAgentModelRequirements(requirements, content) {
             const trimmedContent = content.trim();
             if (!trimmedContent) {
-                return {
-                    ...requirements,
-                    parentAgentUrl: undefined,
-                };
+                return requirements;
             }
             if (trimmedContent.toUpperCase() === 'VOID' ||
                 trimmedContent.toUpperCase() === 'NULL' ||
@@ -14554,6 +14569,136 @@
      * Note: [💞] Ignore a discrepancy between file name and entity name
      */
 
+    /**
+     * @@@
+     *
+     * @private thing of inline knowledge
+     */
+    const INLINE_KNOWLEDGE_BASE_NAME = 'inline-knowledge';
+    /**
+     * @@@
+     *
+     * @private thing of inline knowledge
+     */
+    const INLINE_KNOWLEDGE_EXTENSION = '.txt';
+    /**
+     * @@@
+     *
+     * @private thing of inline knowledge
+     */
+    const DATA_URL_PREFIX = 'data:';
+    /**
+     * @@@
+     *
+     * @private thing of inline knowledge
+     */
+    function getFirstNonEmptyLine(content) {
+        const lines = content.split(/\r?\n/);
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (trimmed) {
+                return trimmed;
+            }
+        }
+        return null;
+    }
+    /**
+     * @@@
+     *
+     * @private thing of inline knowledge
+     */
+    function deriveBaseFilename(content) {
+        const firstLine = getFirstNonEmptyLine(content);
+        if (!firstLine) {
+            return INLINE_KNOWLEDGE_BASE_NAME;
+        }
+        const normalized = normalizeToKebabCase(firstLine);
+        return normalized || INLINE_KNOWLEDGE_BASE_NAME;
+    }
+    /**
+     * Creates a data URL that represents the inline knowledge content as a text file.
+     *
+     * @private thing of inline knowledge
+     */
+    function createInlineKnowledgeSourceFile(content) {
+        const trimmedContent = content.trim();
+        const baseName = deriveBaseFilename(trimmedContent);
+        const filename = `${baseName}${INLINE_KNOWLEDGE_EXTENSION}`;
+        const mimeType = 'text/plain';
+        const base64 = Buffer.from(trimmedContent, 'utf-8').toString('base64');
+        const encodedFilename = encodeURIComponent(filename);
+        const url = `${DATA_URL_PREFIX}${mimeType};name=${encodedFilename};charset=utf-8;base64,${base64}`;
+        return {
+            filename,
+            mimeType,
+            url,
+        };
+    }
+    /**
+     * Checks whether the provided source string is a data URL that can be decoded.
+     *
+     * @private thing of inline knowledge
+     */
+    function isDataUrlKnowledgeSource(source) {
+        return typeof source === 'string' && source.startsWith(DATA_URL_PREFIX);
+    }
+    /**
+     * Parses a data URL-based knowledge source into its raw buffer, filename, and MIME type.
+     *
+     * @private thing of inline knowledge
+     */
+    function parseDataUrlKnowledgeSource(source) {
+        if (!isDataUrlKnowledgeSource(source)) {
+            return null;
+        }
+        const commaIndex = source.indexOf(',');
+        if (commaIndex === -1) {
+            return null;
+        }
+        const header = source.slice(DATA_URL_PREFIX.length, commaIndex);
+        const payload = source.slice(commaIndex + 1);
+        const tokens = header.split(';');
+        const mediaType = tokens[0] || 'text/plain';
+        let filename = `${INLINE_KNOWLEDGE_BASE_NAME}${INLINE_KNOWLEDGE_EXTENSION}`;
+        let isBase64 = false;
+        for (let i = 1; i < tokens.length; i++) {
+            const token = tokens[i];
+            if (!token) {
+                continue;
+            }
+            if (token.toLowerCase() === 'base64') {
+                isBase64 = true;
+                continue;
+            }
+            const [key, value] = token.split('=');
+            if (key === 'name' && value !== undefined) {
+                try {
+                    filename = decodeURIComponent(value);
+                }
+                catch (_a) {
+                    filename = value;
+                }
+            }
+        }
+        if (!isBase64) {
+            return null;
+        }
+        try {
+            const buffer = Buffer.from(payload, 'base64');
+            return {
+                buffer,
+                filename,
+                mimeType: mediaType,
+            };
+        }
+        catch (_b) {
+            return null;
+        }
+    }
+    /**
+     * Note: [💞] Ignore a discrepancy between file name and entity name
+     */
+
     /**
      * KNOWLEDGE commitment definition
      *
@@ -14652,9 +14797,13 @@
                 return this.appendToSystemMessage(updatedRequirements, knowledgeInfo, '\n\n');
             }
             else {
-                // Direct text knowledge - add to system message
-                const knowledgeSection = `Knowledge: ${trimmedContent}`;
-                return this.appendToSystemMessage(requirements, knowledgeSection, '\n\n');
+                const inlineSource = createInlineKnowledgeSourceFile(trimmedContent);
+                const updatedRequirements = {
+                    ...requirements,
+                    knowledgeSources: [...(requirements.knowledgeSources || []), inlineSource.url],
+                };
+                const knowledgeInfo = `Knowledge Source Inline: ${inlineSource.filename} (derived from inline content and processed for retrieval during chat)`;
+                return this.appendToSystemMessage(updatedRequirements, knowledgeInfo, '\n\n');
             }
         }
     }
@@ -14901,16 +15050,16 @@
             // and typically doesn't need to be added to the system prompt or model requirements directly.
             // It is extracted separately for the chat interface.
             var _a;
-            const pendingUserMessage = (_a = requirements.metadata) === null || _a === void 0 ? void 0 : _a.pendingUserMessage;
+            const pendingUserMessage = (_a = requirements._metadata) === null || _a === void 0 ? void 0 : _a.pendingUserMessage;
             if (pendingUserMessage) {
                 const newSample = { question: pendingUserMessage, answer: content };
                 const newSamples = [...(requirements.samples || []), newSample];
-                const newMetadata = { ...requirements.metadata };
+                const newMetadata = { ...requirements._metadata };
                 delete newMetadata.pendingUserMessage;
                 return {
                     ...requirements,
                     samples: newSamples,
-                    metadata: newMetadata,
+                    _metadata: newMetadata,
                 };
             }
             return requirements;
@@ -15158,8 +15307,8 @@
         applyToAgentModelRequirements(requirements, content) {
             return {
                 ...requirements,
-                metadata: {
-                    ...requirements.metadata,
+                _metadata: {
+                    ...requirements._metadata,
                     pendingUserMessage: content,
                 },
             };
@@ -16017,11 +16166,7 @@
             if (trimmedContent === '') {
                 return requirements;
             }
-            // Return requirements with updated notes but no changes to system message
-            return {
-                ...requirements,
-                notes: [...(requirements.notes || []), trimmedContent],
-            };
+            return requirements;
         }
     }
     /**
@@ -16083,12 +16228,12 @@
             // Since OPEN is default, we can just ensure isClosed is false
             // But to be explicit we can set it
             const updatedMetadata = {
-                ...requirements.metadata,
+                ...requirements._metadata,
                 isClosed: false,
             };
             return {
                 ...requirements,
-                metadata: updatedMetadata,
+                _metadata: updatedMetadata,
             };
         }
     }
@@ -16169,7 +16314,7 @@
                 return requirements;
             }
             // Get existing persona content from metadata
-            const existingPersonaContent = ((_a = requirements.metadata) === null || _a === void 0 ? void 0 : _a.PERSONA) || '';
+            const existingPersonaContent = ((_a = requirements._metadata) === null || _a === void 0 ? void 0 : _a.PERSONA) || '';
             // Merge the new content with existing persona content
             // When multiple PERSONA commitments exist, they are merged into one
             const mergedPersonaContent = existingPersonaContent
@@ -16177,12 +16322,12 @@
                 : trimmedContent;
             // Store the merged persona content in metadata for debugging and inspection
             const updatedMetadata = {
-                ...requirements.metadata,
+                ...requirements._metadata,
                 PERSONA: mergedPersonaContent,
             };
             // Get the agent name from metadata (which should contain the first line of agent source)
             // If not available, extract from current system message as fallback
-            let agentName = (_b = requirements.metadata) === null || _b === void 0 ? void 0 : _b.agentName;
+            let agentName = (_b = requirements._metadata) === null || _b === void 0 ? void 0 : _b.agentName;
             if (!agentName) {
                 // Fallback: extract from current system message
                 const currentMessage = requirements.systemMessage.trim();
@@ -16229,7 +16374,7 @@
             return {
                 ...requirements,
                 systemMessage: newSystemMessage,
-                metadata: updatedMetadata,
+                _metadata: updatedMetadata,
             };
         }
     }
@@ -16312,7 +16457,16 @@
             }
             // Add rule to the system message
             const ruleSection = `Rule: ${trimmedContent}`;
-            return this.appendToSystemMessage(requirements, ruleSection, '\n\n');
+            const requirementsWithRule = this.appendToSystemMessage(requirements, ruleSection, '\n\n');
+            const ruleLines = trimmedContent
+                .split(/\r?\n/)
+                .map((line) => line.trim())
+                .filter(Boolean)
+                .map((line) => `- ${line}`);
+            if (ruleLines.length === 0) {
+                return requirementsWithRule;
+            }
+            return this.appendToPromptSuffix(requirementsWithRule, ruleLines.join('\n'));
         }
     }
     /**
@@ -16818,7 +16972,7 @@
             if (teammates.length === 0) {
                 return requirements;
             }
-            const agentName = ((_a = requirements.metadata) === null || _a === void 0 ? void 0 : _a.agentName) || 'Agent';
+            const agentName = ((_a = requirements._metadata) === null || _a === void 0 ? void 0 : _a.agentName) || 'Agent';
             const teamEntries = teammates.map((teammate) => ({
                 toolName: createTeamToolName(teammate.url),
                 teammate,
@@ -16858,7 +17012,7 @@
                     },
                 });
             }
-            const existingTeammates = ((_b = requirements.metadata) === null || _b === void 0 ? void 0 : _b.teammates) || [];
+            const existingTeammates = ((_b = requirements._metadata) === null || _b === void 0 ? void 0 : _b.teammates) || [];
             const updatedTeammates = [...existingTeammates];
             for (const entry of teamEntries) {
                 if (updatedTeammates.some((existing) => existing.url === entry.teammate.url)) {
@@ -16887,8 +17041,8 @@
             return this.appendToSystemMessage({
                 ...requirements,
                 tools: updatedTools,
-                metadata: {
-                    ...requirements.metadata,
+                _metadata: {
+                    ...requirements._metadata,
                     teammates: updatedTeammates,
                 },
             }, teamSystemMessage);
@@ -16988,11 +17142,16 @@
             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);
@@ -17002,6 +17161,7 @@
                 teammate: teammateMetadata,
                 request,
                 response: teammateReply,
+                toolCalls: toolCalls && toolCalls.length > 0 ? toolCalls : undefined,
                 error,
                 conversation: [
                     {
@@ -17114,7 +17274,7 @@
             if (!trimmedContent) {
                 // Store template mode flag in metadata
                 const updatedMetadata = {
-                    ...requirements.metadata,
+                    ...requirements._metadata,
                     templateMode: true,
                 };
                 // Add a general instruction about using structured templates
@@ -17124,21 +17284,21 @@
             `);
                 return {
                     ...this.appendToSystemMessage(requirements, templateModeInstruction, '\n\n'),
-                    metadata: updatedMetadata,
+                    _metadata: updatedMetadata,
                 };
             }
             // If content is provided, add the specific template instructions
             const templateSection = `Response Template: ${trimmedContent}`;
             // Store the template in metadata for potential programmatic access
-            const existingTemplates = ((_a = requirements.metadata) === null || _a === void 0 ? void 0 : _a.templates) || [];
+            const existingTemplates = ((_a = requirements._metadata) === null || _a === void 0 ? void 0 : _a.templates) || [];
             const updatedMetadata = {
-                ...requirements.metadata,
+                ...requirements._metadata,
                 templates: [...existingTemplates, trimmedContent],
                 templateMode: true,
             };
             return {
                 ...this.appendToSystemMessage(requirements, templateSection, '\n\n'),
-                metadata: updatedMetadata,
+                _metadata: updatedMetadata,
             };
         }
     }
@@ -17475,8 +17635,8 @@
             return this.appendToSystemMessage({
                 ...requirements,
                 tools: updatedTools,
-                metadata: {
-                    ...requirements.metadata,
+                _metadata: {
+                    ...requirements._metadata,
                     useBrowser: true,
                 },
             }, spaceTrim$1.spaceTrim(`
@@ -17705,8 +17865,8 @@
             return this.appendToSystemMessage({
                 ...requirements,
                 tools: updatedTools,
-                metadata: {
-                    ...requirements.metadata,
+                _metadata: {
+                    ...requirements._metadata,
                     useEmail: content || true,
                 },
             }, spaceTrim$1.spaceTrim((block) => `
@@ -17841,8 +18001,8 @@
             return this.appendToSystemMessage({
                 ...requirements,
                 tools: updatedTools,
-                metadata: {
-                    ...requirements.metadata,
+                _metadata: {
+                    ...requirements._metadata,
                     useImageGenerator: content || true,
                 },
             }, spaceTrim$1.spaceTrim(`
@@ -18133,8 +18293,8 @@
             return this.appendToSystemMessage({
                 ...requirements,
                 tools: updatedTools,
-                metadata: {
-                    ...requirements.metadata,
+                _metadata: {
+                    ...requirements._metadata,
                     useSearchEngine: content || true,
                 },
             }, spaceTrim$1.spaceTrim((block) => `
@@ -18282,8 +18442,8 @@
             return this.appendToSystemMessage({
                 ...requirements,
                 tools: updatedTools,
-                metadata: {
-                    ...requirements.metadata,
+                _metadata: {
+                    ...requirements._metadata,
                 },
             }, spaceTrim$1.spaceTrim((block) => `
                     Time and date context:
@@ -20317,6 +20477,40 @@
         return toolCall.name === ASSISTANT_PREPARATION_TOOL_CALL_NAME;
     }
 
+    /**
+     * Builds a stable identity string for tool calls across partial updates.
+     *
+     * @param toolCall - Tool call entry to identify.
+     * @returns Stable identity string for deduplication.
+     *
+     * @private function of <Chat/>
+     */
+    function getToolCallIdentity(toolCall) {
+        const rawToolCall = toolCall.rawToolCall;
+        const rawId = (rawToolCall === null || rawToolCall === void 0 ? void 0 : rawToolCall.id) || (rawToolCall === null || rawToolCall === void 0 ? void 0 : rawToolCall.callId) || (rawToolCall === null || rawToolCall === void 0 ? void 0 : rawToolCall.call_id);
+        if (rawId) {
+            return `id:${rawId}`;
+        }
+        if (toolCall.createdAt) {
+            return `time:${toolCall.createdAt}:${toolCall.name}`;
+        }
+        const argsKey = (() => {
+            if (typeof toolCall.arguments === 'string') {
+                return toolCall.arguments;
+            }
+            if (!toolCall.arguments) {
+                return '';
+            }
+            try {
+                return JSON.stringify(toolCall.arguments);
+            }
+            catch (_a) {
+                return '';
+            }
+        })();
+        return `fallback:${toolCall.name}:${argsKey}`;
+    }
+
     /*! *****************************************************************************
     Copyright (c) Microsoft Corporation.
 
@@ -20955,11 +21149,14 @@
     function createEmptyAgentModelRequirements() {
         return {
             systemMessage: '',
+            promptSuffix: '',
             // modelName: 'gpt-5',
             modelName: 'gemini-2.5-flash-lite',
             temperature: 0.7,
             topP: 0.9,
             topK: 50,
+            parentAgentUrl: null,
+            isClosed: false,
         };
     }
     /**
@@ -21105,14 +21302,26 @@
     }
 
     /**
-     * Creates agent model requirements using the new commitment system
+     * Creates agent model requirements using the new commitment system.
+     *
      * This function uses a reduce-like pattern where each commitment applies its changes
-     * to build the final requirements starting from a basic empty model
+     * to build the final requirements starting from a basic empty model.
      *
-     * @public exported from `@promptbook/core`
+     * @param agentSource - Agent source book to parse.
+     * @param modelName - Optional override for the agent model name.
+     * @param options - Additional options such as the agent reference resolver.
+     *
+     * @private @@@
+     */
+    const COMMITMENTS_WITH_AGENT_REFERENCES = new Set(['FROM', 'IMPORT', 'IMPORTS', 'TEAM']);
+    /**
+     * @@@
+     *
+     * @private @@@
      */
-    async function createAgentModelRequirementsWithCommitments(agentSource, modelName) {
+    async function createAgentModelRequirementsWithCommitments(agentSource, modelName, options) {
         var _a;
+        const agentReferenceResolver = options === null || options === void 0 ? void 0 : options.agentReferenceResolver;
         // Parse the agent source to extract commitments
         const parseResult = parseAgentSourceWithCommitments(agentSource);
         // Apply DELETE filtering: remove prior commitments tagged by parameters targeted by DELETE/CANCEL/DISCARD/REMOVE
@@ -21149,8 +21358,8 @@
         // Store the agent name in metadata so commitments can access it
         requirements = {
             ...requirements,
-            metadata: {
-                ...requirements.metadata,
+            _metadata: {
+                ...requirements._metadata,
                 agentName: parseResult.agentName,
             },
         };
@@ -21164,6 +21373,11 @@
         // Apply each commitment in order using reduce-like pattern
         for (let i = 0; i < filteredCommitments.length; i++) {
             const commitment = filteredCommitments[i];
+            const isReferenceCommitment = Boolean(agentReferenceResolver && COMMITMENTS_WITH_AGENT_REFERENCES.has(commitment.type));
+            let commitmentContent = commitment.content;
+            if (isReferenceCommitment && agentReferenceResolver) {
+                commitmentContent = await agentReferenceResolver.resolveCommitmentContent(commitment.type, commitment.content);
+            }
             // CLOSED commitment should work only if its the last commitment in the book
             if (commitment.type === 'CLOSED' && i !== filteredCommitments.length - 1) {
                 continue;
@@ -21171,7 +21385,7 @@
             const definition = getCommitmentDefinition(commitment.type);
             if (definition) {
                 try {
-                    requirements = definition.applyToAgentModelRequirements(requirements, commitment.content);
+                    requirements = definition.applyToAgentModelRequirements(requirements, commitmentContent);
                 }
                 catch (error) {
                     console.warn(`Failed to apply commitment ${commitment.type}:`, error);
@@ -21319,23 +21533,28 @@
     }
 
     /**
-     * Creates model requirements for an agent based on its source
+     * Creates model requirements for an agent based on its source.
      *
      * There are 2 similar functions:
      * - `parseAgentSource` which is a lightweight parser for agent source, it parses basic information and its purpose is to be quick and synchronous. The commitments there are hardcoded.
      * - `createAgentModelRequirements` which is an asynchronous function that creates model requirements it applies each commitment one by one and works asynchronous.
      *
+     * @param agentSource - Book describing the agent.
+     * @param modelName - Optional override for the agent's model.
+     * @param availableModels - Models that could fulfill the agent.
+     * @param llmTools - Execution tools used when selecting a best model.
+     * @param options - Optional hooks such as the agent reference resolver.
      * @public exported from `@promptbook/core`
      */
-    async function createAgentModelRequirements(agentSource, modelName, availableModels, llmTools) {
+    async function createAgentModelRequirements(agentSource, modelName, availableModels, llmTools, options) {
         // If availableModels are provided and no specific modelName is given,
         // use preparePersona to select the best model
         if (availableModels && !modelName && llmTools) {
             const selectedModelName = await selectBestModelUsingPersona(agentSource, llmTools);
-            return createAgentModelRequirementsWithCommitments(agentSource, selectedModelName);
+            return createAgentModelRequirementsWithCommitments(agentSource, selectedModelName, options);
         }
         // Use the new commitment-based system with provided or default model
-        return createAgentModelRequirementsWithCommitments(agentSource, modelName);
+        return createAgentModelRequirementsWithCommitments(agentSource, modelName, options);
     }
     /**
      * Selects the best model using the preparePersona function
@@ -21633,6 +21852,66 @@
             },
             /**/
             /**/
+            {
+                modelVariant: 'CHAT',
+                modelTitle: 'gpt-5.2-codex',
+                modelName: 'gpt-5.2-codex',
+                modelDescription: 'High-capability Codex variant tuned for agentic code generation with large contexts and reasoning effort controls. Ideal for long-horizon coding workflows and multi-step reasoning.',
+                pricing: {
+                    prompt: pricing(`$1.75 / 1M tokens`),
+                    output: pricing(`$14.00 / 1M tokens`),
+                },
+            },
+            /**/
+            /**/
+            {
+                modelVariant: 'CHAT',
+                modelTitle: 'gpt-5.1-codex-max',
+                modelName: 'gpt-5.1-codex-max',
+                modelDescription: 'Premium GPT-5.1 Codex flavor that mirrors gpt-5.1 in capability and pricing while adding Codex tooling optimizations.',
+                pricing: {
+                    prompt: pricing(`$1.25 / 1M tokens`),
+                    output: pricing(`$10.00 / 1M tokens`),
+                },
+            },
+            /**/
+            /**/
+            {
+                modelVariant: 'CHAT',
+                modelTitle: 'gpt-5.1-codex',
+                modelName: 'gpt-5.1-codex',
+                modelDescription: 'Core GPT-5.1 Codex model focused on agentic coding tasks with a balanced trade-off between reasoning and cost.',
+                pricing: {
+                    prompt: pricing(`$1.25 / 1M tokens`),
+                    output: pricing(`$10.00 / 1M tokens`),
+                },
+            },
+            /**/
+            /**/
+            {
+                modelVariant: 'CHAT',
+                modelTitle: 'gpt-5.1-codex-mini',
+                modelName: 'gpt-5.1-codex-mini',
+                modelDescription: 'Compact, cost-effective GPT-5.1 Codex variant with a smaller context window ideal for cheap assistant iterations that still require coding awareness.',
+                pricing: {
+                    prompt: pricing(`$0.25 / 1M tokens`),
+                    output: pricing(`$2.00 / 1M tokens`),
+                },
+            },
+            /**/
+            /**/
+            {
+                modelVariant: 'CHAT',
+                modelTitle: 'gpt-5-codex',
+                modelName: 'gpt-5-codex',
+                modelDescription: 'Legacy GPT-5 Codex model built for agentic coding workloads with the same pricing as GPT-5 and a focus on stability.',
+                pricing: {
+                    prompt: pricing(`$1.25 / 1M tokens`),
+                    output: pricing(`$10.00 / 1M tokens`),
+                },
+            },
+            /**/
+            /**/
             {
                 modelVariant: 'CHAT',
                 modelTitle: 'gpt-5-mini',
@@ -22337,6 +22616,32 @@
             errorMessage.includes('does not support'));
     }
 
+    /**
+     * Provides access to the structured clone implementation when available.
+     */
+    function getStructuredCloneFunction() {
+        return globalThis.structuredClone;
+    }
+    /**
+     * Checks whether the prompt is a chat prompt that carries file attachments.
+     */
+    function hasChatPromptFiles(prompt) {
+        return 'files' in prompt && Array.isArray(prompt.files);
+    }
+    /**
+     * Creates a deep copy of the prompt while keeping attached files intact when structured clone is not available.
+     */
+    function clonePromptPreservingFiles(prompt) {
+        const structuredCloneFn = getStructuredCloneFunction();
+        if (typeof structuredCloneFn === 'function') {
+            return structuredCloneFn(prompt);
+        }
+        const clonedPrompt = JSON.parse(JSON.stringify(prompt));
+        if (hasChatPromptFiles(prompt)) {
+            clonedPrompt.files = prompt.files;
+        }
+        return clonedPrompt;
+    }
     /**
      * Execution Tools for calling OpenAI API or other OpenAI compatible provider
      *
@@ -22366,16 +22671,11 @@
                 const openAiOptions = { ...this.options };
                 delete openAiOptions.isVerbose;
                 delete openAiOptions.userId;
-                // Enhanced configuration for better ECONNRESET handling
+                // Enhanced configuration with retries and timeouts.
                 const enhancedOptions = {
                     ...openAiOptions,
                     timeout: API_REQUEST_TIMEOUT,
                     maxRetries: CONNECTION_RETRIES_LIMIT,
-                    defaultHeaders: {
-                        Connection: 'keep-alive',
-                        'Keep-Alive': 'timeout=30, max=100',
-                        ...openAiOptions.defaultHeaders,
-                    },
                 };
                 this.client = new OpenAI__default["default"](enhancedOptions);
             }
@@ -22426,7 +22726,7 @@
          */
         async callChatModelStream(prompt, onProgress) {
             // Deep clone prompt and modelRequirements to avoid mutation across calls
-            const clonedPrompt = JSON.parse(JSON.stringify(prompt));
+            const clonedPrompt = clonePromptPreservingFiles(prompt);
             // Use local Set for retried parameters to ensure independence and thread safety
             const retriedUnsupportedParameters = new Set();
             return this.callChatModelWithRetry(clonedPrompt, clonedPrompt.modelRequirements, [], retriedUnsupportedParameters, onProgress);
@@ -22453,7 +22753,10 @@
                 // <- TODO: [🈁] Use `seed` here AND/OR use is `isDeterministic` for entire execution tools
                 // <- Note: [🧆]
             }; // <- TODO: [💩] Guard here types better
-            if (format === 'JSON') {
+            if (currentModelRequirements.responseFormat !== undefined) {
+                modelSettings.response_format = currentModelRequirements.responseFormat;
+            }
+            else if (format === 'JSON') {
                 modelSettings.response_format = {
                     type: 'json_object',
                 };
@@ -23264,18 +23567,6 @@
         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)
          *
@@ -23310,206 +23601,1259 @@
         }
     }
 
+    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 using the Responses API (Agents)
+     * Base class for OpenAI execution tools that need hosted vector stores.
      *
      * @public exported from `@promptbook/openai`
      */
-    class OpenAiAgentExecutionTools extends OpenAiExecutionTools {
-        constructor(options) {
-            super(options);
-            this.vectorStoreId = options.vectorStoreId;
+    class OpenAiVectorStoreHandler extends OpenAiExecutionTools {
+        /**
+         * Returns the per-knowledge-source download timeout in milliseconds.
+         */
+        getKnowledgeSourceDownloadTimeoutMs() {
+            var _a;
+            return (_a = this.vectorStoreOptions.knowledgeSourceDownloadTimeoutMs) !== null && _a !== void 0 ? _a : DEFAULT_KNOWLEDGE_SOURCE_DOWNLOAD_TIMEOUT_MS;
         }
-        get title() {
-            return 'OpenAI Agent';
+        /**
+         * Returns the max concurrency for knowledge source uploads.
+         */
+        getKnowledgeSourceUploadMaxConcurrency() {
+            var _a;
+            return (_a = this.vectorStoreOptions.knowledgeSourceUploadMaxConcurrency) !== null && _a !== void 0 ? _a : 5;
         }
-        get description() {
-            return 'Use OpenAI Responses API (Agentic)';
+        /**
+         * Returns the polling interval in milliseconds for vector store uploads.
+         */
+        getKnowledgeSourceUploadPollIntervalMs() {
+            var _a;
+            return (_a = this.vectorStoreOptions.knowledgeSourceUploadPollIntervalMs) !== null && _a !== void 0 ? _a : 5000;
         }
         /**
-         * Calls OpenAI API to use a chat model with streaming.
+         * Returns the overall upload timeout in milliseconds for vector store uploads.
          */
-        async callChatModelStream(prompt, onProgress) {
+        getKnowledgeSourceUploadTimeoutMs() {
+            var _a;
+            return (_a = this.vectorStoreOptions.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.vectorStoreOptions.shouldContinueOnVectorStoreStall) !== null && _a !== void 0 ? _a : true;
+        }
+        /**
+         * Returns vector-store-specific options with extended settings.
+         */
+        get vectorStoreOptions() {
+            return this.options;
+        }
+        /**
+         * Returns the OpenAI vector stores API surface, supporting stable and beta SDKs.
+         */
+        getVectorStoresApi(client) {
+            var _a, _b;
+            const vectorStores = (_a = client.vectorStores) !== null && _a !== void 0 ? _a : (_b = client.beta) === null || _b === void 0 ? void 0 : _b.vectorStores;
+            if (!vectorStores) {
+                throw new Error('OpenAI client does not support vector stores. Please ensure you are using a compatible version of the OpenAI SDK with vector store support.');
+            }
+            return vectorStores;
+        }
+        /**
+         * 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('💬 OpenAI Agent callChatModel call', { prompt });
+                console.info('[🤰]', 'Downloading knowledge source', {
+                    source,
+                    timeoutMs,
+                    logLabel,
+                });
             }
-            const { content, parameters, modelRequirements } = prompt;
-            const client = await this.getClient();
-            if (modelRequirements.modelVariant !== 'CHAT') {
-                throw new PipelineExecutionError('Use callChatModel only for CHAT variant');
+            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;
+                }
+                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('[🤰]', 'Downloaded knowledge source', {
+                        source,
+                        filename,
+                        sizeBytes,
+                        contentType,
+                        elapsedMs,
+                        logLabel,
+                    });
+                }
+                return { file, sizeBytes, filename, elapsedMs };
             }
-            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);
+            catch (error) {
+                assertsError(error);
+                console.error('[🤰]', 'Error downloading knowledge source', {
+                    source,
+                    elapsedMs: Date.now() - startedAtMs,
+                    logLabel,
+                    error: serializeError(error),
+                });
+                return null;
             }
-            // 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],
-                    },
+            finally {
+                clearTimeout(timeoutId);
+            }
+        }
+        /**
+         * Logs vector store file batch diagnostics to help trace ingestion stalls or failures.
+         */
+        async logVectorStoreFileBatchDiagnostics(options) {
+            var _a, _b, _c, _d, _e;
+            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 vectorStores = this.getVectorStoresApi(client);
+                const limit = Math.min(100, Math.max(10, uploadedFiles.length));
+                const batchFilesPage = await vectorStores.fileBatches.listFiles(batchId, {
+                    vector_store_id: vectorStoreId,
+                    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) {
+                    const status = (_b = file.status) !== null && _b !== void 0 ? _b : 'unknown';
+                    statusCounts[status] = ((_c = statusCounts[status]) !== null && _c !== void 0 ? _c : 0) + 1;
+                    const vectorStoreFileId = file.id;
+                    const uploadedFileId = (_d = file.file_id) !== null && _d !== void 0 ? _d : file.fileId;
+                    const fileId = uploadedFileId !== null && uploadedFileId !== void 0 ? uploadedFileId : vectorStoreFileId;
+                    batchFileIds.add(fileId);
+                    const metadata = fileIdToMetadata.get(fileId);
+                    if (status === 'failed') {
+                        errorSamples.push({
+                            fileId,
+                            status,
+                            error: (_e = file.last_error) === null || _e === void 0 ? void 0 : _e.message,
+                            filename: metadata === null || metadata === void 0 ? void 0 : metadata.filename,
+                            vectorStoreFileId: uploadedFileId ? vectorStoreFileId : undefined,
+                        });
+                    }
+                    if (status === 'in_progress') {
+                        inProgressSamples.push({
+                            fileId,
+                            filename: metadata === null || metadata === void 0 ? void 0 : metadata.filename,
+                            vectorStoreFileId: uploadedFileId ? vectorStoreFileId : undefined,
+                        });
+                    }
+                }
+                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 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, _e, _f;
+            const { client, vectorStoreId, files, totalBytes, logLabel } = options;
+            const vectorStores = this.getVectorStoresApi(client);
+            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('[🤰]', 'Uploaded knowledge source file', {
+                                index: uploadIndex,
+                                total: files.length,
+                                filename,
+                                sizeBytes,
+                                fileId: uploaded.id,
+                                elapsedMs: Date.now() - fileUploadStartedAtMs,
+                                logLabel,
+                            });
+                        }
+                    }
+                    catch (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,
+                        });
+                    }
+                }
+            };
+            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 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: string | undefined;
+            let lastCountsKey = '';
+            let lastProgressKey = '';
+            let lastLogAtMs = 0;
+            let lastProgressAtMs = pollStartedAtMs;
+            let lastDiagnosticsAtMs = pollStartedAtMs;
+            let latestBatch = batch;
+            let loggedBatchIdMismatch = false;
+            let loggedBatchIdFallback = false;
+            let loggedBatchIdInvalid = false;
+            let shouldPoll = true;
+            while (shouldPoll) {
+                const nowMs = Date.now();
+                // [🤰] Note: Sometimes OpenAI returns Vector Store object instead of Batch object, or IDs get swapped.
+                const rawBatchId = typeof latestBatch.id === 'string' ? latestBatch.id : '';
+                const rawVectorStoreId = latestBatch.vector_store_id;
+                let returnedBatchId = rawBatchId;
+                let returnedBatchIdValid = typeof returnedBatchId === 'string' && returnedBatchId.startsWith('vsfb_');
+                if (!returnedBatchIdValid && expectedBatchIdValid) {
+                    if (!loggedBatchIdFallback) {
+                        console.error('[🤰]', 'Vector store file batch id missing from response; falling back to expected', {
+                            vectorStoreId,
+                            expectedBatchId,
+                            returnedBatchId,
+                            rawVectorStoreId,
+                            logLabel,
+                        });
+                        loggedBatchIdFallback = true;
+                    }
+                    returnedBatchId = expectedBatchId;
+                    returnedBatchIdValid = true;
+                }
+                if (!returnedBatchIdValid && !loggedBatchIdInvalid) {
+                    console.error('[🤰]', 'Vector store file batch id is invalid; stopping polling', {
+                        vectorStoreId,
+                        expectedBatchId,
+                        returnedBatchId,
+                        rawVectorStoreId,
+                        logLabel,
+                    });
+                    loggedBatchIdInvalid = true;
+                }
+                const batchIdMismatch = expectedBatchIdValid && returnedBatchIdValid && returnedBatchId !== expectedBatchId;
+                if (batchIdMismatch && !loggedBatchIdMismatch) {
+                    console.error('[🤰]', 'Vector store file batch id mismatch', {
+                        vectorStoreId,
+                        expectedBatchId,
+                        returnedBatchId,
+                        logLabel,
+                    });
+                    loggedBatchIdMismatch = true;
+                }
+                if (returnedBatchIdValid) {
+                    latestBatch = await vectorStores.fileBatches.retrieve(returnedBatchId, {
+                        vector_store_id: vectorStoreId,
+                    });
+                }
+                else {
+                    shouldPoll = false;
+                    continue;
+                }
+                const status = (_e = latestBatch.status) !== null && _e !== void 0 ? _e : 'unknown';
+                const fileCounts = (_f = latestBatch.file_counts) !== null && _f !== void 0 ? _f : {};
+                const progressKey = JSON.stringify(fileCounts);
+                const statusCountsKey = `${status}-${progressKey}`;
+                const isProgressing = progressKey !== lastProgressKey;
+                if (isProgressing) {
+                    lastProgressAtMs = nowMs;
+                    lastProgressKey = progressKey;
+                }
+                if (this.options.isVerbose &&
+                    (statusCountsKey !== lastCountsKey || nowMs - lastLogAtMs >= progressLogIntervalMs)) {
+                    console.info('[🤰]', 'Vector store file batch status', {
+                        vectorStoreId,
+                        batchId: returnedBatchId,
+                        status,
+                        fileCounts,
+                        elapsedMs: nowMs - pollStartedAtMs,
+                        logLabel,
+                    });
+                    lastCountsKey = statusCountsKey;
+                    lastLogAtMs = nowMs;
+                }
+                if (status === 'in_progress' &&
+                    nowMs - lastProgressAtMs >= VECTOR_STORE_STALL_LOG_THRESHOLD_MS &&
+                    nowMs - lastDiagnosticsAtMs >= diagnosticsIntervalMs) {
+                    lastDiagnosticsAtMs = nowMs;
+                    await this.logVectorStoreFileBatchDiagnostics({
+                        client,
+                        vectorStoreId,
+                        batchId: returnedBatchId,
+                        uploadedFiles,
+                        logLabel,
+                        reason: 'stalled',
+                    });
+                }
+                if (status === 'completed') {
+                    if (this.options.isVerbose) {
+                        console.info('[🤰]', 'Vector store file batch completed', {
+                            vectorStoreId,
+                            batchId: returnedBatchId,
+                            fileCounts,
+                            elapsedMs: nowMs - pollStartedAtMs,
+                            logLabel,
+                        });
+                    }
+                    shouldPoll = false;
+                    continue;
+                }
+                if (status === 'failed') {
+                    console.error('[🤰]', 'Vector store file batch completed with failures', {
+                        vectorStoreId,
+                        batchId: returnedBatchId,
+                        fileCounts,
+                        elapsedMs: nowMs - pollStartedAtMs,
+                        logLabel,
+                    });
+                    await this.logVectorStoreFileBatchDiagnostics({
+                        client,
+                        vectorStoreId,
+                        batchId: returnedBatchId,
+                        uploadedFiles,
+                        logLabel,
+                        reason: 'failed',
+                    });
+                    shouldPoll = false;
+                    continue;
+                }
+                if (status === 'cancelled') {
+                    console.error('[🤰]', 'Vector store file batch did not complete', {
+                        vectorStoreId,
+                        batchId: returnedBatchId,
+                        status,
+                        fileCounts,
+                        elapsedMs: nowMs - pollStartedAtMs,
+                        logLabel,
+                    });
+                    await this.logVectorStoreFileBatchDiagnostics({
+                        client,
+                        vectorStoreId,
+                        batchId: returnedBatchId,
+                        uploadedFiles,
+                        logLabel,
+                        reason: 'failed',
+                    });
+                    shouldPoll = false;
+                    continue;
+                }
+                if (nowMs - pollStartedAtMs >= uploadTimeoutMs) {
+                    console.error('[🤰]', 'Timed out waiting for vector store file batch', {
+                        vectorStoreId,
+                        batchId: returnedBatchId,
+                        fileCounts,
+                        elapsedMs: nowMs - pollStartedAtMs,
+                        uploadTimeoutMs,
+                        logLabel,
+                    });
+                    await this.logVectorStoreFileBatchDiagnostics({
+                        client,
+                        vectorStoreId,
+                        batchId: returnedBatchId,
+                        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 vectorStores.fileBatches.cancel(cancelBatchId, {
+                                vector_store_id: vectorStoreId,
+                            });
+                        }
+                        if (this.options.isVerbose) {
+                            console.info('[🤰]', 'Cancelled vector store file batch after timeout', {
+                                vectorStoreId,
+                                batchId: batchIdMismatch && returnedBatchId.startsWith('vsfb_')
+                                    ? returnedBatchId
+                                    : expectedBatchId,
+                                ...(batchIdMismatch ? { returnedBatchId } : {}),
+                                logLabel,
+                            });
+                        }
+                    }
+                    catch (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 vectorStores = this.getVectorStoresApi(client);
+            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 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 isDataUrl = isDataUrlKnowledgeSource(source);
+                    const isHttp = source.startsWith('http://') || source.startsWith('https://');
+                    const sourceType = isDataUrl ? 'data_url' : isHttp ? 'url' : 'file';
+                    if (this.options.isVerbose) {
+                        console.info('[🤰]', 'Processing knowledge source', {
+                            index: index + 1,
+                            total: knowledgeSourcesCount,
+                            source,
+                            sourceType,
+                            logLabel,
+                        });
+                    }
+                    if (isDataUrl) {
+                        const parsed = parseDataUrlKnowledgeSource(source);
+                        if (!parsed) {
+                            skippedSources.push({ source, reason: 'invalid_data_url' });
+                            if (this.options.isVerbose) {
+                                console.info('[🤰]', 'Skipping knowledge source (invalid data URL)', {
+                                    source,
+                                    sourceType,
+                                    logLabel,
+                                });
+                            }
+                            continue;
+                        }
+                        const dataUrlFile = new File([parsed.buffer], parsed.filename, {
+                            type: parsed.mimeType,
+                        });
+                        fileStreams.push(dataUrlFile);
+                        totalBytes += parsed.buffer.length;
+                        continue;
+                    }
+                    if (isHttp) {
+                        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,
+            };
+        }
+    }
+
+    const DEFAULT_AGENT_KIT_MODEL_NAME = 'gpt-5.2';
+    const DEFAULT_JSON_SCHEMA_NAME = 'StructuredOutput';
+    /*
+    TODO: Use or remove
+    const EMPTY_JSON_SCHEMA: JsonSchemaDefinition['schema'] = {
+        type: 'object',
+        properties: {},
+        required: [],
+        additionalProperties: true,
+    };
+    */
+    function buildJsonSchemaDefinition(jsonSchema) {
+        var _a, _b, _c;
+        const schema = (_a = jsonSchema === null || jsonSchema === void 0 ? void 0 : jsonSchema.schema) !== null && _a !== void 0 ? _a : {};
+        return {
+            type: 'json_schema',
+            name: (_b = jsonSchema === null || jsonSchema === void 0 ? void 0 : jsonSchema.name) !== null && _b !== void 0 ? _b : DEFAULT_JSON_SCHEMA_NAME,
+            strict: Boolean(jsonSchema === null || jsonSchema === void 0 ? void 0 : jsonSchema.strict),
+            schema: {
+                type: 'object',
+                properties: ((_c = schema.properties) !== null && _c !== void 0 ? _c : {}),
+                required: Array.isArray(schema.required) ? schema.required : [],
+                additionalProperties: schema.additionalProperties === undefined ? true : Boolean(schema.additionalProperties),
+                description: schema.description,
+            },
+        };
+    }
+    /**
+     * Maps OpenAI `response_format` payloads to AgentKit output types so the runner can forward
+     * structured-output preferences to OpenAI while still reusing the same AgentKit agent instance.
+     *
+     * @param responseFormat - The OpenAI `response_format` payload from the user request.
+     * @returns An Agent output type compatible with the requested schema or `undefined` when no impact is required.
+     * @private utility of Open AI
+     */
+    function mapResponseFormatToAgentOutputType(responseFormat) {
+        if (!responseFormat) {
+            return undefined;
+        }
+        if (typeof responseFormat === 'string') {
+            if (responseFormat === 'text') {
+                return 'text';
+            }
+            if (responseFormat === 'json_schema' || responseFormat === 'json_object') {
+                return buildJsonSchemaDefinition();
+            }
+            return 'text';
+        }
+        switch (responseFormat.type) {
+            case 'text':
+                return 'text';
+            case 'json_schema':
+                return buildJsonSchemaDefinition(responseFormat.json_schema);
+            case 'json_object':
+                return buildJsonSchemaDefinition();
+            default:
+                return undefined;
+        }
+    }
+    /**
+     * Execution tools for OpenAI AgentKit (Agents SDK).
+     *
+     * @public exported from `@promptbook/openai`
+     */
+    class OpenAiAgentKitExecutionTools extends OpenAiVectorStoreHandler {
+        /**
+         * Creates OpenAI AgentKit execution tools.
+         */
+        constructor(options) {
+            var _a;
+            if (options.isProxied) {
+                throw new NotYetImplementedError(`Proxy mode is not yet implemented for OpenAI AgentKit`);
+            }
+            super(options);
+            this.preparedAgentKitAgent = null;
+            this.agentKitModelName = (_a = options.agentKitModelName) !== null && _a !== void 0 ? _a : DEFAULT_AGENT_KIT_MODEL_NAME;
+        }
+        get title() {
+            return 'OpenAI AgentKit';
+        }
+        get description() {
+            return 'Use OpenAI AgentKit for agent-style chat with tools and knowledge';
+        }
+        /**
+         * Calls OpenAI AgentKit with a chat prompt (non-streaming).
+         */
+        async callChatModel(prompt) {
+            return this.callChatModelStream(prompt, () => { });
+        }
+        /**
+         * Calls OpenAI AgentKit with a chat prompt (streaming).
+         */
+        async callChatModelStream(prompt, onProgress) {
+            const { content, parameters, modelRequirements } = prompt;
+            if (modelRequirements.modelVariant !== 'CHAT') {
+                throw new PipelineExecutionError('Use callChatModel only for CHAT variant');
+            }
+            for (const key of ['maxTokens', 'modelName', 'seed', 'temperature']) {
+                if (modelRequirements[key] !== undefined) {
+                    throw new NotYetImplementedError(`In \`OpenAiAgentKitExecutionTools\` you cannot specify \`${key}\``);
+                }
+            }
+            const rawPromptContent = templateParameters(content, {
+                ...parameters,
+                modelName: this.agentKitModelName,
+            });
+            const responseFormatOutputType = mapResponseFormatToAgentOutputType(modelRequirements.responseFormat);
+            const preparedAgentKitAgent = await this.prepareAgentKitAgent({
+                name: (prompt.title || 'Agent'),
+                instructions: modelRequirements.systemMessage || '',
+                knowledgeSources: modelRequirements.knowledgeSources,
+                tools: 'tools' in prompt && Array.isArray(prompt.tools) ? prompt.tools : modelRequirements.tools,
+            });
+            return this.callChatModelStreamWithPreparedAgent({
+                openAiAgentKitAgent: preparedAgentKitAgent.agent,
+                prompt,
+                rawPromptContent,
+                onProgress,
+                responseFormatOutputType,
+            });
+        }
+        /**
+         * Returns a prepared AgentKit agent when the server wants to manage caching externally.
+         */
+        getPreparedAgentKitAgent() {
+            return this.preparedAgentKitAgent;
+        }
+        /**
+         * Stores a prepared AgentKit agent for later reuse by external cache managers.
+         */
+        setPreparedAgentKitAgent(preparedAgent) {
+            this.preparedAgentKitAgent = preparedAgent;
+        }
+        /**
+         * Creates a new tools instance bound to a prepared AgentKit agent.
+         */
+        getPreparedAgentTools(preparedAgent) {
+            const tools = new OpenAiAgentKitExecutionTools(this.agentKitOptions);
+            tools.setPreparedAgentKitAgent(preparedAgent);
+            return tools;
+        }
+        /**
+         * Prepares an AgentKit agent with optional knowledge sources and tool definitions.
+         */
+        async prepareAgentKitAgent(options) {
+            var _a, _b;
+            const { name, instructions, knowledgeSources, tools, vectorStoreId: cachedVectorStoreId, storeAsPrepared, } = options;
+            await this.ensureAgentKitDefaults();
+            if (this.options.isVerbose) {
+                console.info('[🤰]', 'Preparing OpenAI AgentKit agent', {
+                    name,
+                    instructionsLength: instructions.length,
+                    knowledgeSourcesCount: (_a = knowledgeSources === null || knowledgeSources === void 0 ? void 0 : knowledgeSources.length) !== null && _a !== void 0 ? _a : 0,
+                    toolsCount: (_b = tools === null || tools === void 0 ? void 0 : tools.length) !== null && _b !== void 0 ? _b : 0,
+                });
+            }
+            let vectorStoreId = cachedVectorStoreId;
+            if (!vectorStoreId && knowledgeSources && knowledgeSources.length > 0) {
+                const vectorStoreResult = await this.createVectorStoreWithKnowledgeSources({
+                    client: await this.getClient(),
+                    name,
+                    knowledgeSources,
+                    logLabel: 'agentkit preparation',
+                });
+                vectorStoreId = vectorStoreResult.vectorStoreId;
+            }
+            else if (vectorStoreId && this.options.isVerbose) {
+                console.info('[🤰]', 'Using cached vector store for AgentKit agent', {
+                    name,
+                    vectorStoreId,
+                });
+            }
+            const agentKitTools = this.buildAgentKitTools({ tools, vectorStoreId });
+            const openAiAgentKitAgent = new agents.Agent({
+                name,
+                model: this.agentKitModelName,
+                instructions: instructions || 'You are a helpful assistant.',
+                tools: agentKitTools,
+            });
+            const preparedAgent = {
+                agent: openAiAgentKitAgent,
+                vectorStoreId,
+            };
+            if (storeAsPrepared) {
+                this.setPreparedAgentKitAgent(preparedAgent);
+            }
+            if (this.options.isVerbose) {
+                console.info('[🤰]', 'OpenAI AgentKit agent ready', {
+                    name,
+                    model: this.agentKitModelName,
+                    toolCount: agentKitTools.length,
+                    hasVectorStore: Boolean(vectorStoreId),
+                });
+            }
+            return preparedAgent;
+        }
+        /**
+         * Ensures the AgentKit SDK is wired to the OpenAI client and API key.
+         */
+        async ensureAgentKitDefaults() {
+            const client = await this.getClient();
+            agents.setDefaultOpenAIClient(client);
+            const apiKey = this.agentKitOptions.apiKey;
+            if (apiKey && typeof apiKey === 'string') {
+                agents.setDefaultOpenAIKey(apiKey);
+            }
+        }
+        /**
+         * Builds the tool list for AgentKit, including hosted file search when applicable.
+         */
+        buildAgentKitTools(options) {
+            var _a;
+            const { tools, vectorStoreId } = options;
+            const agentKitTools = [];
+            if (vectorStoreId) {
+                agentKitTools.push(agents.fileSearchTool(vectorStoreId));
+            }
+            if (tools && tools.length > 0) {
+                const scriptTools = this.resolveScriptTools();
+                for (const toolDefinition of tools) {
+                    agentKitTools.push(agents.tool({
+                        name: toolDefinition.name,
+                        description: toolDefinition.description,
+                        parameters: toolDefinition.parameters
+                            ? {
+                                ...toolDefinition.parameters,
+                                additionalProperties: false,
+                                required: (_a = toolDefinition.parameters.required) !== null && _a !== void 0 ? _a : [],
+                            }
+                            : undefined,
+                        strict: false,
+                        execute: async (input, runContext, details) => {
+                            var _a, _b, _c;
+                            const scriptTool = scriptTools[0];
+                            const functionName = toolDefinition.name;
+                            const calledAt = $getCurrentDate();
+                            const callId = (_a = details === null || details === void 0 ? void 0 : details.toolCall) === null || _a === void 0 ? void 0 : _a.callId;
+                            const functionArgs = input !== null && input !== void 0 ? input : {};
+                            if (this.options.isVerbose) {
+                                console.info('[🤰]', 'Executing AgentKit tool', {
+                                    functionName,
+                                    callId,
+                                    calledAt,
+                                });
+                            }
+                            try {
+                                return await scriptTool.execute({
+                                    scriptLanguage: 'javascript',
+                                    script: `
+                                        const args = ${JSON.stringify(functionArgs)};
+                                        return await ${functionName}(args);
+                                    `,
+                                    parameters: (_c = (_b = runContext === null || runContext === void 0 ? void 0 : runContext.context) === null || _b === void 0 ? void 0 : _b.parameters) !== null && _c !== void 0 ? _c : {},
+                                });
+                            }
+                            catch (error) {
+                                assertsError(error);
+                                const serializedError = serializeError(error);
+                                const errorMessage = spaceTrim__default["default"]((block) => `
+
+                                        The invoked tool \`${functionName}\` failed with error:
+
+                                        \`\`\`json
+                                        ${block(JSON.stringify(serializedError, null, 4))}
+                                        \`\`\`
+
+                                    `);
+                                console.error('[🤰]', 'AgentKit tool execution failed', {
+                                    functionName,
+                                    callId,
+                                    error: serializedError,
+                                });
+                                return errorMessage;
+                            }
+                        },
+                    }));
+                }
             }
-            // 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.');
+            return agentKitTools;
+        }
+        /**
+         * Resolves the configured script tools for tool execution.
+         */
+        resolveScriptTools() {
+            const executionTools = this.options.executionTools;
+            if (!executionTools || !executionTools.script) {
+                throw new PipelineExecutionError(`Model requested tools but no executionTools.script were provided in OpenAiAgentKitExecutionTools options`);
             }
+            return Array.isArray(executionTools.script) ? executionTools.script : [executionTools.script];
+        }
+        /**
+         * Runs a prepared AgentKit agent and streams results back to the caller.
+         */
+        async callChatModelStreamWithPreparedAgent(options) {
+            var _a, _b, _c, _d;
+            const { openAiAgentKitAgent, prompt, onProgress } = options;
+            const rawPromptContent = (_a = options.rawPromptContent) !== null && _a !== void 0 ? _a : templateParameters(prompt.content, {
+                ...prompt.parameters,
+                modelName: this.agentKitModelName,
+            });
+            const agentForRun = options.responseFormatOutputType !== undefined
+                ? openAiAgentKitAgent.clone({
+                    outputType: options.responseFormatOutputType,
+                })
+                : openAiAgentKitAgent;
             const start = $getCurrentDate();
-            // Construct the request
+            let latestContent = '';
+            const toolCalls = [];
+            const toolCallIndexById = new Map();
+            const inputItems = await this.buildAgentKitInputItems(prompt, rawPromptContent);
             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
+                agentName: agentForRun.name,
+                input: inputItems,
             };
-            if (this.options.isVerbose) {
-                console.info(colors__default["default"].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__default["default"].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;
-                            }
+            const streamResult = await agents.run(agentForRun, inputItems, {
+                stream: true,
+                context: { parameters: prompt.parameters },
+            });
+            for await (const event of streamResult) {
+                if (event.type === 'raw_model_stream_event' && ((_b = event.data) === null || _b === void 0 ? void 0 : _b.type) === 'output_text_delta') {
+                    latestContent += event.data.delta;
+                    onProgress({
+                        content: latestContent,
+                        modelName: this.agentKitModelName,
+                        timing: { start, complete: $getCurrentDate() },
+                        usage: UNCERTAIN_USAGE,
+                        rawPromptContent: rawPromptContent,
+                        rawRequest: null,
+                        rawResponse: {},
+                    });
+                    continue;
+                }
+                if (event.type === 'run_item_stream_event') {
+                    const rawItem = (_c = event.item) === null || _c === void 0 ? void 0 : _c.rawItem;
+                    if (event.name === 'tool_called' && (rawItem === null || rawItem === void 0 ? void 0 : rawItem.type) === 'function_call') {
+                        const toolCall = {
+                            name: rawItem.name,
+                            arguments: rawItem.arguments,
+                            rawToolCall: rawItem,
+                            createdAt: $getCurrentDate(),
+                        };
+                        toolCallIndexById.set(rawItem.callId, toolCalls.length);
+                        toolCalls.push(toolCall);
+                        onProgress({
+                            content: latestContent,
+                            modelName: this.agentKitModelName,
+                            timing: { start, complete: $getCurrentDate() },
+                            usage: UNCERTAIN_USAGE,
+                            rawPromptContent: rawPromptContent,
+                            rawRequest: null,
+                            rawResponse: {},
+                            toolCalls: [toolCall],
+                        });
+                    }
+                    if (event.name === 'tool_output' && (rawItem === null || rawItem === void 0 ? void 0 : rawItem.type) === 'function_call_result') {
+                        const index = toolCallIndexById.get(rawItem.callId);
+                        const result = this.formatAgentKitToolOutput(rawItem.output);
+                        if (index !== undefined) {
+                            const existingToolCall = toolCalls[index];
+                            const completedToolCall = {
+                                ...existingToolCall,
+                                result,
+                                rawToolCall: rawItem,
+                            };
+                            toolCalls[index] = completedToolCall;
+                            onProgress({
+                                content: latestContent,
+                                modelName: this.agentKitModelName,
+                                timing: { start, complete: $getCurrentDate() },
+                                usage: UNCERTAIN_USAGE,
+                                rawPromptContent: rawPromptContent,
+                                rawRequest: null,
+                                rawResponse: {},
+                                toolCalls: [completedToolCall],
+                            });
                         }
                     }
-                    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',
+            await streamResult.completed;
+            const complete = $getCurrentDate();
+            const finalContent = ((_d = streamResult.finalOutput) !== null && _d !== void 0 ? _d : latestContent);
+            const finalResult = {
+                content: finalContent,
+                modelName: this.agentKitModelName,
                 timing: { start, complete },
                 usage: UNCERTAIN_USAGE,
-                rawPromptContent,
+                rawPromptContent: 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,
-                },
-            });
+                rawResponse: { runResult: streamResult },
+                toolCalls: toolCalls.length > 0 ? toolCalls : undefined,
+            };
+            onProgress(finalResult);
+            return finalResult;
         }
         /**
-         * Creates a vector store from knowledge sources
+         * Builds AgentKit input items from the prompt and optional thread.
          */
-        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);
+        async buildAgentKitInputItems(prompt, rawPromptContent) {
+            var _a;
+            const inputItems = [];
+            if ('thread' in prompt && Array.isArray(prompt.thread)) {
+                for (const message of prompt.thread) {
+                    const sender = message.sender;
+                    const content = (_a = message.content) !== null && _a !== void 0 ? _a : '';
+                    if (sender === 'assistant' || sender === 'agent') {
+                        inputItems.push({
+                            role: 'assistant',
+                            status: 'completed',
+                            content: [{ type: 'output_text', text: content }],
+                        });
                     }
                     else {
-                        // Local files not supported in browser env easily, same as before
+                        inputItems.push({
+                            role: 'user',
+                            content,
+                        });
                     }
                 }
-                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);
+            const userContent = await this.buildAgentKitUserContent(prompt, rawPromptContent);
+            inputItems.push({
+                role: 'user',
+                content: userContent,
+            });
+            return inputItems;
+        }
+        /**
+         * Builds the user message content for AgentKit runs, including file inputs when provided.
+         */
+        async buildAgentKitUserContent(prompt, rawPromptContent) {
+            if ('files' in prompt && Array.isArray(prompt.files) && prompt.files.length > 0) {
+                const fileItems = await Promise.all(prompt.files.map(async (file) => {
+                    const arrayBuffer = await file.arrayBuffer();
+                    const base64 = Buffer.from(arrayBuffer).toString('base64');
+                    return {
+                        type: 'input_image',
+                        image: `data:${file.type};base64,${base64}`,
+                    };
+                }));
+                return [{ type: 'input_text', text: rawPromptContent }, ...fileItems];
+            }
+            return rawPromptContent;
+        }
+        /**
+         * Normalizes AgentKit tool outputs into a string for Promptbook tool call results.
+         */
+        formatAgentKitToolOutput(output) {
+            if (typeof output === 'string') {
+                return output;
+            }
+            if (output && typeof output === 'object') {
+                const textOutput = output;
+                if (textOutput.type === 'text' && typeof textOutput.text === 'string') {
+                    return textOutput.text;
                 }
             }
-            return vectorStoreId;
+            return JSON.stringify(output !== null && output !== void 0 ? output : null);
         }
         /**
-         * Discriminant for type guards
+         * Returns AgentKit-specific options.
+         */
+        get agentKitOptions() {
+            return this.options;
+        }
+        /**
+         * Discriminant for type guards.
          */
         get discriminant() {
-            return 'OPEN_AI_AGENT';
+            return DISCRIMINANT$1;
         }
         /**
-         * Type guard to check if given `LlmExecutionTools` are instanceof `OpenAiAgentExecutionTools`
+         * Type guard to check if given `LlmExecutionTools` are instanceof `OpenAiAgentKitExecutionTools`.
          */
-        static isOpenAiAgentExecutionTools(llmExecutionTools) {
-            return llmExecutionTools.discriminant === 'OPEN_AI_AGENT';
+        static isOpenAiAgentKitExecutionTools(llmExecutionTools) {
+            return llmExecutionTools.discriminant === DISCRIMINANT$1;
         }
     }
+    /**
+     * Discriminant for type guards.
+     *
+     * @private const of `OpenAiAgentKitExecutionTools`
+     */
+    const DISCRIMINANT$1 = 'OPEN_AI_AGENT_KIT_V1';
 
     /**
      * Uploads files to OpenAI and returns their IDs
@@ -23544,10 +24888,10 @@
      * - `OpenAiAssistantExecutionTools` - which is a specific implementation of `LlmExecutionTools` for OpenAI models with assistant capabilities, recommended for usage in `Agent` or `AgentLlmExecutionTools`
      * - `RemoteAgent` - which is an `Agent` that connects to a Promptbook Agents Server
      *
+     * @deprecated Use `OpenAiAgentKitExecutionTools` instead.
      * @public exported from `@promptbook/openai`
-     * @deprecated Use `OpenAiAgentExecutionTools` instead which uses the new OpenAI Responses API
      */
-    class OpenAiAssistantExecutionTools extends OpenAiExecutionTools {
+    class OpenAiAssistantExecutionTools extends OpenAiVectorStoreHandler {
         /**
          * Creates OpenAI Execution Tools.
          *
@@ -23676,8 +25020,7 @@
                     console.info(colors__default["default"].bgWhite('rawRequest (non-streaming with tools)'), JSON.stringify(rawRequest, null, 4));
                 }
                 // Create thread and run
-                const threadAndRun = await client.beta.threads.createAndRun(rawRequest);
-                let run = threadAndRun;
+                let run = (await client.beta.threads.createAndRun(rawRequest));
                 const completedToolCalls = [];
                 const toolCallStartedAt = new Map();
                 // Poll until run completes or requires action
@@ -23772,14 +25115,14 @@
                             }
                         }
                         // Submit tool outputs
-                        run = await client.beta.threads.runs.submitToolOutputs(run.thread_id, run.id, {
+                        run = (await client.beta.threads.runs.submitToolOutputs(run.thread_id, run.id, {
                             tool_outputs: toolOutputs,
-                        });
+                        }));
                     }
                     else {
                         // Wait a bit before polling again
                         await new Promise((resolve) => setTimeout(resolve, 500));
-                        run = await client.beta.threads.runs.retrieve(run.thread_id, run.id);
+                        run = (await client.beta.threads.runs.retrieve(run.thread_id, run.id));
                     }
                 }
                 if (run.status !== 'completed') {
@@ -23978,6 +25321,7 @@
         getAssistant(assistantId) {
             return new OpenAiAssistantExecutionTools({
                 ...this.options,
+                isCreatingNewAssistantsAllowed: this.isCreatingNewAssistantsAllowed,
                 assistantId,
             });
         }
@@ -24003,88 +25347,13 @@
             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,
-                    });
-                }
-                // Create a vector store
-                const vectorStore = await client.beta.vectorStores.create({
-                    name: `${name} Knowledge Base`,
+                const vectorStoreResult = await this.createVectorStoreWithKnowledgeSources({
+                    client,
+                    name,
+                    knowledgeSources,
+                    logLabel: 'assistant creation',
                 });
-                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 [index, source] of knowledgeSources.entries()) {
-                    try {
-                        if (this.options.isVerbose) {
-                            console.info('[🤰]', 'Processing knowledge source', {
-                                index: index + 1,
-                                total: knowledgeSources.length,
-                                source,
-                                sourceType: source.startsWith('http') || source.startsWith('https') ? 'url' : 'file',
-                            });
-                        }
-                        // Check if it's a URL
-                        if (source.startsWith('http://') || source.startsWith('https://')) {
-                            // Download the file
-                            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', {
-                                vectorStoreId,
-                                fileCount: fileStreams.length,
-                            });
-                        }
-                    }
-                    catch (error) {
-                        console.error('Error uploading files to vector store:', error);
-                    }
-                }
+                vectorStoreId = vectorStoreResult.vectorStoreId;
             }
             // Create assistant with vector store attached
             const assistantConfig = {
@@ -24151,91 +25420,14 @@
             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,
@@ -24339,8 +25531,8 @@
      * - `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
+     * - `OpenAiAgentKitExecutionTools` - which is a specific implementation of `LlmExecutionTools` backed by OpenAI AgentKit
      * - `RemoteAgent` - which is an `Agent` that connects to a Promptbook Agents Server
      *
      * @public exported from `@promptbook/core`
@@ -24475,97 +25667,129 @@
          * Calls the chat model with agent-specific system prompt and requirements with streaming
          */
         async callChatModelStream(prompt, onProgress) {
+            var _a, _b;
             // Ensure we're working with a chat prompt
             if (prompt.modelRequirements.modelVariant !== 'CHAT') {
                 throw new Error('AgentLlmExecutionTools only supports chat prompts');
             }
             const modelRequirements = await this.getModelRequirements();
+            const { _metadata, promptSuffix, ...sanitizedRequirements } = modelRequirements;
             const chatPrompt = prompt;
             let underlyingLlmResult;
-            // Create modified chat prompt with agent system message
+            const chatPromptContentWithSuffix = promptSuffix
+                ? `${chatPrompt.content}\n\n${promptSuffix}`
+                : chatPrompt.content;
             const promptWithAgentModelRequirements = {
                 ...chatPrompt,
+                content: chatPromptContentWithSuffix,
                 modelRequirements: {
                     ...chatPrompt.modelRequirements,
-                    ...modelRequirements,
+                    ...sanitizedRequirements,
                     // Spread tools to convert readonly array to mutable
-                    tools: modelRequirements.tools ? [...modelRequirements.tools] : chatPrompt.modelRequirements.tools,
+                    tools: sanitizedRequirements.tools
+                        ? [...sanitizedRequirements.tools]
+                        : chatPrompt.modelRequirements.tools,
                     // Spread knowledgeSources to convert readonly array to mutable
-                    knowledgeSources: modelRequirements.knowledgeSources
-                        ? [...modelRequirements.knowledgeSources]
+                    knowledgeSources: sanitizedRequirements.knowledgeSources
+                        ? [...sanitizedRequirements.knowledgeSources]
                         : undefined,
                     // Prepend agent system message to existing system message
-                    systemMessage: modelRequirements.systemMessage +
+                    systemMessage: sanitizedRequirements.systemMessage +
                         (chatPrompt.modelRequirements.systemMessage
                             ? `\n\n${chatPrompt.modelRequirements.systemMessage}`
                             : ''),
                 }, // Cast to avoid readonly mismatch from spread
             };
             console.log('!!!! promptWithAgentModelRequirements:', promptWithAgentModelRequirements);
-            if (OpenAiAgentExecutionTools.isOpenAiAgentExecutionTools(this.options.llmTools)) {
-                const requirementsHash = cryptoJs.SHA256(JSON.stringify(modelRequirements)).toString();
-                const cached = AgentLlmExecutionTools.vectorStoreCache.get(this.title);
-                let agentTools;
-                if (cached && cached.requirementsHash === requirementsHash) {
+            if (OpenAiAgentKitExecutionTools.isOpenAiAgentKitExecutionTools(this.options.llmTools)) {
+                const requirementsHash = cryptoJs.SHA256(JSON.stringify(sanitizedRequirements)).toString();
+                const vectorStoreHash = cryptoJs.SHA256(JSON.stringify((_a = sanitizedRequirements.knowledgeSources) !== null && _a !== void 0 ? _a : [])).toString();
+                const cachedVectorStore = AgentLlmExecutionTools.vectorStoreCache.get(this.title);
+                const cachedAgentKit = AgentLlmExecutionTools.agentKitAgentCache.get(this.title);
+                let preparedAgentKit = this.options.assistantPreparationMode === 'external'
+                    ? this.options.llmTools.getPreparedAgentKitAgent()
+                    : null;
+                const vectorStoreId = (preparedAgentKit === null || preparedAgentKit === void 0 ? void 0 : preparedAgentKit.vectorStoreId) ||
+                    (cachedVectorStore && cachedVectorStore.requirementsHash === vectorStoreHash
+                        ? cachedVectorStore.vectorStoreId
+                        : undefined);
+                if (!preparedAgentKit && cachedAgentKit && cachedAgentKit.requirementsHash === requirementsHash) {
                     if (this.options.isVerbose) {
-                        console.log(`1️⃣ Using cached OpenAI Agent Vector Store for agent ${this.title}...`);
+                        console.info('[🤰]', 'Using cached OpenAI AgentKit agent', {
+                            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,
-                    });
+                    preparedAgentKit = {
+                        agent: cachedAgentKit.agent,
+                        vectorStoreId: cachedAgentKit.vectorStoreId,
+                    };
                 }
-                else {
+                if (!preparedAgentKit) {
                     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);
+                        console.info('[🤰]', 'Preparing OpenAI AgentKit agent', {
+                            agent: this.title,
+                        });
                     }
-                    if (vectorStoreId) {
-                        AgentLlmExecutionTools.vectorStoreCache.set(this.title, {
-                            vectorStoreId,
-                            requirementsHash,
+                    if (!vectorStoreId && ((_b = sanitizedRequirements.knowledgeSources) === null || _b === void 0 ? void 0 : _b.length)) {
+                        emitAssistantPreparationProgress({
+                            onProgress,
+                            prompt,
+                            modelName: this.modelName,
+                            phase: 'Creating knowledge base',
                         });
                     }
-                    agentTools = new OpenAiAgentExecutionTools({
-                        ...this.options.llmTools.options,
+                    emitAssistantPreparationProgress({
+                        onProgress,
+                        prompt,
+                        modelName: this.modelName,
+                        phase: 'Preparing AgentKit agent',
+                    });
+                    preparedAgentKit = await this.options.llmTools.prepareAgentKitAgent({
+                        name: this.title,
+                        instructions: sanitizedRequirements.systemMessage || '',
+                        knowledgeSources: sanitizedRequirements.knowledgeSources,
+                        tools: sanitizedRequirements.tools ? [...sanitizedRequirements.tools] : undefined,
                         vectorStoreId,
                     });
                 }
-                // 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);
+                if (preparedAgentKit.vectorStoreId) {
+                    AgentLlmExecutionTools.vectorStoreCache.set(this.title, {
+                        vectorStoreId: preparedAgentKit.vectorStoreId,
+                        requirementsHash: vectorStoreHash,
+                    });
+                }
+                AgentLlmExecutionTools.agentKitAgentCache.set(this.title, {
+                    agent: preparedAgentKit.agent,
+                    requirementsHash,
+                    vectorStoreId: preparedAgentKit.vectorStoreId,
+                });
+                const responseFormatOutputType = mapResponseFormatToAgentOutputType(promptWithAgentModelRequirements.modelRequirements.responseFormat);
+                underlyingLlmResult = await this.options.llmTools.callChatModelStreamWithPreparedAgent({
+                    openAiAgentKitAgent: preparedAgentKit.agent,
+                    prompt: promptWithAgentModelRequirements,
+                    onProgress,
+                    responseFormatOutputType,
+                });
             }
             else if (OpenAiAssistantExecutionTools.isOpenAiAssistantExecutionTools(this.options.llmTools)) {
                 // ... deprecated path ...
-                const requirementsHash = cryptoJs.SHA256(JSON.stringify(modelRequirements)).toString();
+                const requirementsHash = cryptoJs.SHA256(JSON.stringify(sanitizedRequirements)).toString();
                 const cached = AgentLlmExecutionTools.assistantCache.get(this.title);
                 let assistant;
-                if (cached) {
+                if (this.options.assistantPreparationMode === 'external') {
+                    assistant = this.options.llmTools;
+                    if (this.options.isVerbose) {
+                        console.info('[🤰]', 'Using externally managed OpenAI Assistant', {
+                            agent: this.title,
+                            assistantId: assistant.assistantId,
+                        });
+                    }
+                    AgentLlmExecutionTools.assistantCache.set(this.title, {
+                        assistantId: assistant.assistantId,
+                        requirementsHash,
+                    });
+                }
+                else if (cached) {
                     if (cached.requirementsHash === requirementsHash) {
                         if (this.options.isVerbose) {
                             console.info('[🤰]', 'Using cached OpenAI Assistant', {
@@ -24591,9 +25815,9 @@
                         assistant = await this.options.llmTools.updateAssistant({
                             assistantId: cached.assistantId,
                             name: this.title,
-                            instructions: modelRequirements.systemMessage,
-                            knowledgeSources: modelRequirements.knowledgeSources,
-                            tools: modelRequirements.tools ? [...modelRequirements.tools] : undefined,
+                            instructions: sanitizedRequirements.systemMessage,
+                            knowledgeSources: sanitizedRequirements.knowledgeSources,
+                            tools: sanitizedRequirements.tools ? [...sanitizedRequirements.tools] : undefined,
                         });
                         AgentLlmExecutionTools.assistantCache.set(this.title, {
                             assistantId: assistant.assistantId,
@@ -24616,9 +25840,9 @@
                     });
                     assistant = await this.options.llmTools.createNewAssistant({
                         name: this.title,
-                        instructions: modelRequirements.systemMessage,
-                        knowledgeSources: modelRequirements.knowledgeSources,
-                        tools: modelRequirements.tools ? [...modelRequirements.tools] : undefined,
+                        instructions: sanitizedRequirements.systemMessage,
+                        knowledgeSources: sanitizedRequirements.knowledgeSources,
+                        tools: sanitizedRequirements.tools ? [...sanitizedRequirements.tools] : undefined,
                         /*
                         !!!
                         metadata: {
@@ -24660,18 +25884,28 @@
                 }
             }
             let content = underlyingLlmResult.content;
-            // Note: Cleanup the AI artifacts from the content
-            content = humanizeAiText(content);
-            // Note: Make sure the content is Promptbook-like
-            content = promptbookifyAiText(content);
+            if (typeof content === 'string') {
+                // Note: Cleanup the AI artifacts from the content
+                content = humanizeAiText(content);
+                // Note: Make sure the content is Promptbook-like
+                content = promptbookifyAiText(content);
+            }
+            else {
+                // TODO: Maybe deep `humanizeAiText` + `promptbookifyAiText` inside of the object
+                content = JSON.stringify(content);
+            }
             const agentResult = {
                 ...underlyingLlmResult,
-                content,
+                content: content,
                 modelName: this.modelName,
             };
             return agentResult;
         }
     }
+    /**
+     * Cached AgentKit agents to avoid rebuilding identical instances.
+     */
+    AgentLlmExecutionTools.agentKitAgentCache = new Map();
     /**
      * Cache of OpenAI assistants to avoid creating duplicates
      */
@@ -24752,8 +25986,8 @@
      * - `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
+     * - `OpenAiAgentKitExecutionTools` - which is a specific implementation of `LlmExecutionTools` backed by OpenAI AgentKit
      * - `RemoteAgent` - which is an `Agent` that connects to a Promptbook Agents Server
      *
      * @public exported from `@promptbook/core`
@@ -24784,6 +26018,7 @@
             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);
@@ -24850,7 +26085,6 @@
          * Note: This method also implements the learning mechanism
          */
         async callChatModelStream(prompt, onProgress) {
-            var _a;
             // [1] Check if the user is asking the same thing as in the samples
             const modelRequirements = await this.getModelRequirements();
             if (modelRequirements.samples) {
@@ -24898,7 +26132,7 @@
             if (result.rawResponse && 'sample' in result.rawResponse) {
                 return result;
             }
-            if ((_a = modelRequirements.metadata) === null || _a === void 0 ? void 0 : _a.isClosed) {
+            if (modelRequirements.isClosed) {
                 return result;
             }
             // Note: [0] Notify start of self-learning
@@ -25059,6 +26293,63 @@
      * 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__default["default"]((block) => `
+            PERSONA
+            ${block(profile.personaDescription || '')}
+        `)
+            : '';
+        return book `
+        ${profile.agentName}
+
+        ${metaLines}
+
+        ${personaBlock}
+    `;
+    }
     /**
      * Represents one AI Agent
      *
@@ -25066,13 +26357,15 @@
      * - `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
-     * - `OpenAiAssistantExecutionTools` - which is a specific implementation of `LlmExecutionTools` for OpenAI models with assistant capabilities, recommended for usage in `Agent` or `AgentLlmExecutionTools`
+     * - `OpenAiAssistantExecutionTools` - (Deprecated) which is a specific implementation of `LlmExecutionTools` for OpenAI models with assistant capabilities
+     * - `OpenAiAgentKitExecutionTools` - which is a specific implementation of `LlmExecutionTools` backed by OpenAI AgentKit
      * - `RemoteAgent` - which is an `Agent` that connects to a Promptbook Agents Server
      *
      * @public exported from `@promptbook/core`
      */
     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?
@@ -25092,14 +26385,14 @@
                 
                 `));
             }
-            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 rxjs.BehaviorSubject(book `
-            ${profile.agentName}
-
-            ${profile.personaDescription}
-        `);
+            const agentSource = new rxjs.BehaviorSubject(buildRemoteAgentSource(profile, resolvedMeta));
             // <- TODO: [🐱‍🚀] createBookFromProfile
             // <- TODO: [🐱‍🚀] Support updating and self-updating
             const remoteAgent = new RemoteAgent({
@@ -25122,10 +26415,10 @@
             });
             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 || {};
@@ -25229,26 +26522,7 @@
                 };
             };
             const getToolCallKey = (toolCall) => {
-                var _a;
-                const rawId = (_a = toolCall.rawToolCall) === null || _a === void 0 ? void 0 : _a.id;
-                if (rawId) {
-                    return `id:${rawId}`;
-                }
-                const argsKey = (() => {
-                    if (typeof toolCall.arguments === 'string') {
-                        return toolCall.arguments;
-                    }
-                    if (!toolCall.arguments) {
-                        return '';
-                    }
-                    try {
-                        return JSON.stringify(toolCall.arguments);
-                    }
-                    catch (_a) {
-                        return '';
-                    }
-                })();
-                return `${toolCall.name}:${toolCall.createdAt || ''}:${argsKey}`;
+                return getToolCallIdentity(toolCall);
             };
             const mergeToolCall = (existing, incoming) => {
                 const incomingResult = incoming.result;