@promptbook/wizard 0.110.0-8 → 0.110.0

package/umd/index.umd.js

@@ -49,7 +49,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.110.0-8';
+    const PROMPTBOOK_ENGINE_VERSION = '0.110.0';
     /**
      * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
      * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -3787,6 +3787,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',
@@ -8682,6 +8742,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
      *
@@ -8766,7 +8852,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);
@@ -8793,7 +8879,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',
                 };
@@ -10135,6 +10224,136 @@
         }
     }
 
+    /**
+     * @@@
+     *
+     * @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
+     */
+
     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;
@@ -10771,7 +10990,9 @@
             const processingStartedAtMs = Date.now();
             for (const [index, source] of knowledgeSources.entries()) {
                 try {
-                    const sourceType = source.startsWith('http') || source.startsWith('https') ? 'url' : 'file';
+                    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,
@@ -10781,8 +11002,27 @@
                             logLabel,
                         });
                     }
-                    // Check if it's a URL
-                    if (source.startsWith('http://') || source.startsWith('https://')) {
+                    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,
@@ -17186,11 +17426,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,
         };
     }
     /**
@@ -17307,6 +17550,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
@@ -17484,13 +17749,9 @@
         `);
         }
         applyToAgentModelRequirements(requirements, _content) {
-            const updatedMetadata = {
-                ...requirements.metadata,
-                isClosed: true,
-            };
             return {
                 ...requirements,
-                metadata: updatedMetadata,
+                isClosed: true,
             };
         }
     }
@@ -17768,12 +18029,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
@@ -17781,7 +18042,7 @@
             const dictionarySection = `# DICTIONARY\n${mergedDictionary}`;
             return {
                 ...this.appendToSystemMessage(requirements, dictionarySection),
-                metadata: updatedMetadata,
+                _metadata: updatedMetadata,
             };
         }
     }
@@ -17921,10 +18182,7 @@
         applyToAgentModelRequirements(requirements, content) {
             const trimmedContent = content.trim();
             if (!trimmedContent) {
-                return {
-                    ...requirements,
-                    parentAgentUrl: undefined,
-                };
+                return requirements;
             }
             if (trimmedContent.toUpperCase() === 'VOID' ||
                 trimmedContent.toUpperCase() === 'NULL' ||
@@ -18236,9 +18494,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');
             }
         }
     }
@@ -18485,16 +18747,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;
@@ -18742,8 +19004,8 @@
         applyToAgentModelRequirements(requirements, content) {
             return {
                 ...requirements,
-                metadata: {
-                    ...requirements.metadata,
+                _metadata: {
+                    ...requirements._metadata,
                     pendingUserMessage: content,
                 },
             };
@@ -19601,11 +19863,7 @@
             if (trimmedContent === '') {
                 return requirements;
             }
-            // Return requirements with updated notes but no changes to system message
-            return {
-                ...requirements,
-                notes: [...(requirements.notes || []), trimmedContent],
-            };
+            return requirements;
         }
     }
     /**
@@ -19667,12 +19925,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,
             };
         }
     }
@@ -19753,7 +20011,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
@@ -19761,12 +20019,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();
@@ -19813,7 +20071,7 @@
             return {
                 ...requirements,
                 systemMessage: newSystemMessage,
-                metadata: updatedMetadata,
+                _metadata: updatedMetadata,
             };
         }
     }
@@ -19896,7 +20154,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'));
         }
     }
     /**
@@ -20398,11 +20665,12 @@
             if (!trimmedContent) {
                 return requirements;
             }
-            const teammates = parseTeamCommitmentContent(trimmedContent, { strict: true });
+            // Keep TEAM resilient: unresolved/malformed teammate entries are skipped, valid ones are still registered.
+            const teammates = parseTeamCommitmentContent(trimmedContent, { strict: false });
             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,
@@ -20442,7 +20710,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)) {
@@ -20471,8 +20739,8 @@
             return this.appendToSystemMessage({
                 ...requirements,
                 tools: updatedTools,
-                metadata: {
-                    ...requirements.metadata,
+                _metadata: {
+                    ...requirements._metadata,
                     teammates: updatedTeammates,
                 },
             }, teamSystemMessage);
@@ -20704,7 +20972,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
@@ -20714,21 +20982,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,
             };
         }
     }
@@ -21065,8 +21333,8 @@
             return this.appendToSystemMessage({
                 ...requirements,
                 tools: updatedTools,
-                metadata: {
-                    ...requirements.metadata,
+                _metadata: {
+                    ...requirements._metadata,
                     useBrowser: true,
                 },
             }, spaceTrim$1.spaceTrim(`
@@ -21295,8 +21563,8 @@
             return this.appendToSystemMessage({
                 ...requirements,
                 tools: updatedTools,
-                metadata: {
-                    ...requirements.metadata,
+                _metadata: {
+                    ...requirements._metadata,
                     useEmail: content || true,
                 },
             }, spaceTrim$1.spaceTrim((block) => `
@@ -21431,8 +21699,8 @@
             return this.appendToSystemMessage({
                 ...requirements,
                 tools: updatedTools,
-                metadata: {
-                    ...requirements.metadata,
+                _metadata: {
+                    ...requirements._metadata,
                     useImageGenerator: content || true,
                 },
             }, spaceTrim$1.spaceTrim(`
@@ -21723,8 +21991,8 @@
             return this.appendToSystemMessage({
                 ...requirements,
                 tools: updatedTools,
-                metadata: {
-                    ...requirements.metadata,
+                _metadata: {
+                    ...requirements._metadata,
                     useSearchEngine: content || true,
                 },
             }, spaceTrim$1.spaceTrim((block) => `
@@ -21872,8 +22140,8 @@
             return this.appendToSystemMessage({
                 ...requirements,
                 tools: updatedTools,
-                metadata: {
-                    ...requirements.metadata,
+                _metadata: {
+                    ...requirements._metadata,
                 },
             }, spaceTrim$1.spaceTrim((block) => `
                     Time and date context:
@@ -22457,14 +22725,42 @@
     }
 
     /**
-     * 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 @@@
      */
-    async function createAgentModelRequirementsWithCommitments(agentSource, modelName) {
+    const COMMITMENTS_WITH_AGENT_REFERENCES = new Set(['FROM', 'IMPORT', 'IMPORTS', 'TEAM']);
+    /**
+     * Returns a safe fallback content when a resolver fails to transform a reference commitment.
+     *
+     * @param commitmentType - Commitment being resolved.
+     * @param originalContent - Original unresolved commitment content.
+     * @returns Fallback content that keeps requirement creation resilient.
+     */
+    function getSafeReferenceCommitmentFallback(commitmentType, originalContent) {
+        if (commitmentType === 'FROM') {
+            return 'VOID';
+        }
+        if (commitmentType === 'IMPORT' || commitmentType === 'IMPORTS' || commitmentType === 'TEAM') {
+            return '';
+        }
+        return originalContent;
+    }
+    /**
+     * @@@
+     *
+     * @private @@@
+     */
+    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
@@ -22501,8 +22797,8 @@
         // Store the agent name in metadata so commitments can access it
         requirements = {
             ...requirements,
-            metadata: {
-                ...requirements.metadata,
+            _metadata: {
+                ...requirements._metadata,
                 agentName: parseResult.agentName,
             },
         };
@@ -22516,6 +22812,17 @@
         // 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) {
+                try {
+                    commitmentContent = await agentReferenceResolver.resolveCommitmentContent(commitment.type, commitment.content);
+                }
+                catch (error) {
+                    console.warn(`Failed to resolve commitment references for ${commitment.type}, falling back to safe defaults:`, error);
+                    commitmentContent = getSafeReferenceCommitmentFallback(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;
@@ -22523,7 +22830,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);
@@ -22982,23 +23289,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
@@ -29551,6 +29863,64 @@
      */
 
     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).
      *
@@ -29598,6 +29968,7 @@
                 ...parameters,
                 modelName: this.agentKitModelName,
             });
+            const responseFormatOutputType = mapResponseFormatToAgentOutputType(modelRequirements.responseFormat);
             const preparedAgentKitAgent = await this.prepareAgentKitAgent({
                 name: (prompt.title || 'Agent'),
                 instructions: modelRequirements.systemMessage || '',
@@ -29609,6 +29980,7 @@
                 prompt,
                 rawPromptContent,
                 onProgress,
+                responseFormatOutputType,
             });
         }
         /**
@@ -29790,16 +30162,21 @@
                 ...prompt.parameters,
                 modelName: this.agentKitModelName,
             });
+            const agentForRun = options.responseFormatOutputType !== undefined
+                ? openAiAgentKitAgent.clone({
+                    outputType: options.responseFormatOutputType,
+                })
+                : openAiAgentKitAgent;
             const start = $getCurrentDate();
             let latestContent = '';
             const toolCalls = [];
             const toolCallIndexById = new Map();
             const inputItems = await this.buildAgentKitInputItems(prompt, rawPromptContent);
             const rawRequest = {
-                agentName: openAiAgentKitAgent.name,
+                agentName: agentForRun.name,
                 input: inputItems,
             };
-            const streamResult = await agents.run(openAiAgentKitAgent, inputItems, {
+            const streamResult = await agents.run(agentForRun, inputItems, {
                 stream: true,
                 context: { parameters: prompt.parameters },
             });
@@ -30147,22 +30524,28 @@
                 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}`
                             : ''),
@@ -30170,8 +30553,8 @@
             };
             console.log('!!!! promptWithAgentModelRequirements:', promptWithAgentModelRequirements);
             if (OpenAiAgentKitExecutionTools.isOpenAiAgentKitExecutionTools(this.options.llmTools)) {
-                const requirementsHash = cryptoJs.SHA256(JSON.stringify(modelRequirements)).toString();
-                const vectorStoreHash = cryptoJs.SHA256(JSON.stringify((_a = modelRequirements.knowledgeSources) !== null && _a !== void 0 ? _a : [])).toString();
+                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'
@@ -30198,7 +30581,7 @@
                             agent: this.title,
                         });
                     }
-                    if (!vectorStoreId && ((_b = modelRequirements.knowledgeSources) === null || _b === void 0 ? void 0 : _b.length)) {
+                    if (!vectorStoreId && ((_b = sanitizedRequirements.knowledgeSources) === null || _b === void 0 ? void 0 : _b.length)) {
                         emitAssistantPreparationProgress({
                             onProgress,
                             prompt,
@@ -30214,9 +30597,9 @@
                     });
                     preparedAgentKit = await this.options.llmTools.prepareAgentKitAgent({
                         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,
                         vectorStoreId,
                     });
                 }
@@ -30231,15 +30614,17 @@
                     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 (this.options.assistantPreparationMode === 'external') {
@@ -30281,9 +30666,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,
@@ -30306,9 +30691,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: {
@@ -30350,13 +30735,19 @@
                 }
             }
             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;
@@ -30545,7 +30936,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) {
@@ -30593,7 +30983,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