@promptbook/cli 0.110.0-8 → 0.110.0

package/esm/index.es.js

@@ -48,7 +48,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @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
@@ -15828,6 +15828,28 @@ class BaseCommitmentDefinition {
             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
@@ -16005,13 +16027,9 @@ class ClosedCommitmentDefinition extends BaseCommitmentDefinition {
         `);
     }
     applyToAgentModelRequirements(requirements, _content) {
-        const updatedMetadata = {
-            ...requirements.metadata,
-            isClosed: true,
-        };
         return {
             ...requirements,
-            metadata: updatedMetadata,
+            isClosed: true,
         };
     }
 }
@@ -16289,12 +16307,12 @@ class DictionaryCommitmentDefinition extends BaseCommitmentDefinition {
             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
@@ -16302,7 +16320,7 @@ class DictionaryCommitmentDefinition extends BaseCommitmentDefinition {
         const dictionarySection = `# DICTIONARY\n${mergedDictionary}`;
         return {
             ...this.appendToSystemMessage(requirements, dictionarySection),
-            metadata: updatedMetadata,
+            _metadata: updatedMetadata,
         };
     }
 }
@@ -16442,10 +16460,7 @@ class FromCommitmentDefinition extends BaseCommitmentDefinition {
     applyToAgentModelRequirements(requirements, content) {
         const trimmedContent = content.trim();
         if (!trimmedContent) {
-            return {
-                ...requirements,
-                parentAgentUrl: undefined,
-            };
+            return requirements;
         }
         if (trimmedContent.toUpperCase() === 'VOID' ||
             trimmedContent.toUpperCase() === 'NULL' ||
@@ -16659,6 +16674,136 @@ class ImportCommitmentDefinition extends BaseCommitmentDefinition {
  * 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
  *
@@ -16757,9 +16902,13 @@ class KnowledgeCommitmentDefinition extends BaseCommitmentDefinition {
             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');
         }
     }
 }
@@ -17006,16 +17155,16 @@ class AgentMessageCommitmentDefinition extends BaseCommitmentDefinition {
         // 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;
@@ -17263,8 +17412,8 @@ class UserMessageCommitmentDefinition extends BaseCommitmentDefinition {
     applyToAgentModelRequirements(requirements, content) {
         return {
             ...requirements,
-            metadata: {
-                ...requirements.metadata,
+            _metadata: {
+                ...requirements._metadata,
                 pendingUserMessage: content,
             },
         };
@@ -18122,11 +18271,7 @@ class NoteCommitmentDefinition extends BaseCommitmentDefinition {
         if (trimmedContent === '') {
             return requirements;
         }
-        // Return requirements with updated notes but no changes to system message
-        return {
-            ...requirements,
-            notes: [...(requirements.notes || []), trimmedContent],
-        };
+        return requirements;
     }
 }
 /**
@@ -18188,12 +18333,12 @@ class OpenCommitmentDefinition extends BaseCommitmentDefinition {
         // 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,
         };
     }
 }
@@ -18274,7 +18419,7 @@ class PersonaCommitmentDefinition extends BaseCommitmentDefinition {
             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
@@ -18282,12 +18427,12 @@ class PersonaCommitmentDefinition extends BaseCommitmentDefinition {
             : 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();
@@ -18334,7 +18479,7 @@ class PersonaCommitmentDefinition extends BaseCommitmentDefinition {
         return {
             ...requirements,
             systemMessage: newSystemMessage,
-            metadata: updatedMetadata,
+            _metadata: updatedMetadata,
         };
     }
 }
@@ -18417,7 +18562,16 @@ class RuleCommitmentDefinition extends BaseCommitmentDefinition {
         }
         // 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'));
     }
 }
 /**
@@ -18919,11 +19073,12 @@ class TeamCommitmentDefinition extends BaseCommitmentDefinition {
         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,
@@ -18963,7 +19118,7 @@ class TeamCommitmentDefinition extends BaseCommitmentDefinition {
                 },
             });
         }
-        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)) {
@@ -18992,8 +19147,8 @@ class TeamCommitmentDefinition extends BaseCommitmentDefinition {
         return this.appendToSystemMessage({
             ...requirements,
             tools: updatedTools,
-            metadata: {
-                ...requirements.metadata,
+            _metadata: {
+                ...requirements._metadata,
                 teammates: updatedTeammates,
             },
         }, teamSystemMessage);
@@ -19225,7 +19380,7 @@ class TemplateCommitmentDefinition extends BaseCommitmentDefinition {
         if (!trimmedContent) {
             // Store template mode flag in metadata
             const updatedMetadata = {
-                ...requirements.metadata,
+                ...requirements._metadata,
                 templateMode: true,
             };
             // Add a general instruction about using structured templates
@@ -19235,21 +19390,21 @@ class TemplateCommitmentDefinition extends BaseCommitmentDefinition {
             `);
             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,
         };
     }
 }
@@ -19586,8 +19741,8 @@ class UseBrowserCommitmentDefinition extends BaseCommitmentDefinition {
         return this.appendToSystemMessage({
             ...requirements,
             tools: updatedTools,
-            metadata: {
-                ...requirements.metadata,
+            _metadata: {
+                ...requirements._metadata,
                 useBrowser: true,
             },
         }, spaceTrim$1(`
@@ -19816,8 +19971,8 @@ class UseEmailCommitmentDefinition extends BaseCommitmentDefinition {
         return this.appendToSystemMessage({
             ...requirements,
             tools: updatedTools,
-            metadata: {
-                ...requirements.metadata,
+            _metadata: {
+                ...requirements._metadata,
                 useEmail: content || true,
             },
         }, spaceTrim$1((block) => `
@@ -19952,8 +20107,8 @@ class UseImageGeneratorCommitmentDefinition extends BaseCommitmentDefinition {
         return this.appendToSystemMessage({
             ...requirements,
             tools: updatedTools,
-            metadata: {
-                ...requirements.metadata,
+            _metadata: {
+                ...requirements._metadata,
                 useImageGenerator: content || true,
             },
         }, spaceTrim$1(`
@@ -20244,8 +20399,8 @@ class UseSearchEngineCommitmentDefinition extends BaseCommitmentDefinition {
         return this.appendToSystemMessage({
             ...requirements,
             tools: updatedTools,
-            metadata: {
-                ...requirements.metadata,
+            _metadata: {
+                ...requirements._metadata,
                 useSearchEngine: content || true,
             },
         }, spaceTrim$1((block) => `
@@ -20393,8 +20548,8 @@ class UseTimeCommitmentDefinition extends BaseCommitmentDefinition {
         return this.appendToSystemMessage({
             ...requirements,
             tools: updatedTools,
-            metadata: {
-                ...requirements.metadata,
+            _metadata: {
+                ...requirements._metadata,
             },
         }, spaceTrim$1((block) => `
                     Time and date context:
@@ -24972,6 +25127,66 @@ const OPENAI_MODELS = exportJson({
         },
         /**/
         /**/
+        {
+            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',
@@ -27000,6 +27215,32 @@ function isUnsupportedParameterError(error) {
         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
  *
@@ -27084,7 +27325,7 @@ class OpenAiCompatibleExecutionTools {
      */
     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);
@@ -27111,7 +27352,10 @@ class OpenAiCompatibleExecutionTools {
             // <- 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',
             };
@@ -29089,7 +29333,9 @@ class OpenAiVectorStoreHandler extends OpenAiExecutionTools {
         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,
@@ -29099,8 +29345,27 @@ class OpenAiVectorStoreHandler extends OpenAiExecutionTools {
                         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,
@@ -30985,11 +31250,14 @@ const _FormattedBookInMarkdownTranspilerRegistration = $bookTranspilersRegister.
 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,
     };
 }
 /**
@@ -31379,14 +31647,42 @@ function removeCommentsFromSystemMessage(systemMessage) {
 }
 
 /**
- * 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
@@ -31423,8 +31719,8 @@ async function createAgentModelRequirementsWithCommitments(agentSource, modelNam
     // Store the agent name in metadata so commitments can access it
     requirements = {
         ...requirements,
-        metadata: {
-            ...requirements.metadata,
+        _metadata: {
+            ...requirements._metadata,
             agentName: parseResult.agentName,
         },
     };
@@ -31438,6 +31734,17 @@ async function createAgentModelRequirementsWithCommitments(agentSource, modelNam
     // 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;
@@ -31445,7 +31752,7 @@ async function createAgentModelRequirementsWithCommitments(agentSource, modelNam
         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);
@@ -31904,23 +32211,28 @@ function normalizeSeparator(content) {
  */
 
 /**
- * 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
@@ -32674,6 +32986,64 @@ function promptbookifyAiText(text) {
  */
 
 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).
  *
@@ -32721,6 +33091,7 @@ class OpenAiAgentKitExecutionTools extends OpenAiVectorStoreHandler {
             ...parameters,
             modelName: this.agentKitModelName,
         });
+        const responseFormatOutputType = mapResponseFormatToAgentOutputType(modelRequirements.responseFormat);
         const preparedAgentKitAgent = await this.prepareAgentKitAgent({
             name: (prompt.title || 'Agent'),
             instructions: modelRequirements.systemMessage || '',
@@ -32732,6 +33103,7 @@ class OpenAiAgentKitExecutionTools extends OpenAiVectorStoreHandler {
             prompt,
             rawPromptContent,
             onProgress,
+            responseFormatOutputType,
         });
     }
     /**
@@ -32913,16 +33285,21 @@ class OpenAiAgentKitExecutionTools extends OpenAiVectorStoreHandler {
             ...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 run(openAiAgentKitAgent, inputItems, {
+        const streamResult = await run(agentForRun, inputItems, {
             stream: true,
             context: { parameters: prompt.parameters },
         });
@@ -33270,22 +33647,28 @@ class AgentLlmExecutionTools {
             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}`
                         : ''),
@@ -33293,8 +33676,8 @@ class AgentLlmExecutionTools {
         };
         console.log('!!!! promptWithAgentModelRequirements:', promptWithAgentModelRequirements);
         if (OpenAiAgentKitExecutionTools.isOpenAiAgentKitExecutionTools(this.options.llmTools)) {
-            const requirementsHash = SHA256(JSON.stringify(modelRequirements)).toString();
-            const vectorStoreHash = SHA256(JSON.stringify((_a = modelRequirements.knowledgeSources) !== null && _a !== void 0 ? _a : [])).toString();
+            const requirementsHash = SHA256(JSON.stringify(sanitizedRequirements)).toString();
+            const vectorStoreHash = 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'
@@ -33321,7 +33704,7 @@ class AgentLlmExecutionTools {
                         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,
@@ -33337,9 +33720,9 @@ class AgentLlmExecutionTools {
                 });
                 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,
                 });
             }
@@ -33354,15 +33737,17 @@ class AgentLlmExecutionTools {
                 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 = SHA256(JSON.stringify(modelRequirements)).toString();
+            const requirementsHash = SHA256(JSON.stringify(sanitizedRequirements)).toString();
             const cached = AgentLlmExecutionTools.assistantCache.get(this.title);
             let assistant;
             if (this.options.assistantPreparationMode === 'external') {
@@ -33404,9 +33789,9 @@ class AgentLlmExecutionTools {
                     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,
@@ -33429,9 +33814,9 @@ class AgentLlmExecutionTools {
                 });
                 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: {
@@ -33473,13 +33858,19 @@ class AgentLlmExecutionTools {
             }
         }
         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;
@@ -33668,7 +34059,6 @@ class Agent extends AgentLlmExecutionTools {
      * 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) {
@@ -33716,7 +34106,7 @@ class Agent extends AgentLlmExecutionTools {
         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