@promptbook/node 0.112.0-26 → 0.112.0-28

package/esm/index.es.js

@@ -14,8 +14,8 @@ import { forTime } from 'waitasecond';
 import * as dotenv from 'dotenv';
 import sha256 from 'crypto-js/sha256';
 import { Subject, BehaviorSubject } from 'rxjs';
-import { lookup, extension } from 'mime-types';
 import moment from 'moment';
+import { lookup, extension } from 'mime-types';
 import { parse, unparse } from 'papaparse';
 import { Agent as Agent$1, setDefaultOpenAIClient, setDefaultOpenAIKey, fileSearchTool, tool, run } from '@openai/agents';
 import Bottleneck from 'bottleneck';
@@ -35,7 +35,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.112.0-26';
+const PROMPTBOOK_ENGINE_VERSION = '0.112.0-28';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -19183,6 +19183,147 @@ class UseCommitmentDefinition extends BaseCommitmentDefinition {
  * Note: [💞] Ignore a discrepancy between file name and entity name
  */
 
+/**
+ * All `USE` commitment types currently participating in final system-message aggregation.
+ *
+ * @private internal constant for `aggregateUseCommitmentSystemMessages`
+ */
+const AGGREGATED_USE_COMMITMENT_TYPES = ['USE BROWSER', 'USE SEARCH ENGINE', 'USE TIME'];
+/**
+ * Prefix used for temporary in-system-message placeholders that preserve the first-occurrence position of aggregated `USE` sections.
+ *
+ * @private internal constant for `appendAggregatedUseCommitmentPlaceholder`
+ */
+const AGGREGATED_USE_COMMITMENT_PLACEHOLDER_PREFIX = '# AGGREGATED USE COMMITMENT: ';
+/**
+ * Type guard for `USE` commitment types that are aggregated in the final system message.
+ *
+ * @param type - Commitment type to check.
+ * @returns `true` when the commitment participates in `USE` system-message aggregation.
+ * @private internal utility of `aggregateUseCommitmentSystemMessages`
+ */
+function isAggregatedUseCommitmentType(type) {
+    return AGGREGATED_USE_COMMITMENT_TYPES.includes(type);
+}
+/**
+ * Creates the placeholder token used to reserve the first-occurrence position of an aggregated `USE` system-message section.
+ *
+ * @param type - Aggregated `USE` commitment type.
+ * @returns Single-line placeholder comment stored in the interim system message.
+ * @private internal utility of `appendAggregatedUseCommitmentPlaceholder`
+ */
+function getAggregatedUseCommitmentPlaceholder(type) {
+    return `${AGGREGATED_USE_COMMITMENT_PLACEHOLDER_PREFIX}${type}`;
+}
+/**
+ * Combines distinct additional instruction blocks in source order.
+ *
+ * @param additionalInstructions - Deduplicated instruction blocks collected from the agent source.
+ * @returns Combined instruction text ready for `formatOptionalInstructionBlock`.
+ * @private internal utility of `createAggregatedUseCommitmentSystemMessage`
+ */
+function combineAdditionalInstructions(additionalInstructions) {
+    return additionalInstructions.join('\n');
+}
+/**
+ * Creates the final aggregated system-message section for a supported `USE` commitment type.
+ *
+ * @param type - Aggregated `USE` commitment type.
+ * @param additionalInstructions - Distinct additional instructions in source order.
+ * @returns Final system-message block for the commitment type.
+ * @private internal utility of `aggregateUseCommitmentSystemMessages`
+ */
+function createAggregatedUseCommitmentSystemMessage(type, additionalInstructions) {
+    const combinedAdditionalInstructions = combineAdditionalInstructions(additionalInstructions);
+    switch (type) {
+        case 'USE TIME':
+            return spaceTrim$1((block) => `
+                    Time and date context:
+                    - It is ${moment().format('MMMM YYYY')} now.
+                    - If you need more precise current time information, use the tool "get_current_time".
+                    ${block(formatOptionalInstructionBlock('Time instructions', combinedAdditionalInstructions))}
+                `);
+        case 'USE BROWSER':
+            return spaceTrim$1((block) => `
+                    You have access to browser tools to fetch and access content from the internet.
+                    - Use "fetch_url_content" to retrieve content from specific URLs (webpages or documents) using scrapers.
+                    - Use "run_browser" for real interactive browser automation (navigation, clicks, typing, waiting, scrolling).
+                    When you need to know information from a specific website or document, use the fetch_url_content tool.
+                    ${block(formatOptionalInstructionBlock('Browser instructions', combinedAdditionalInstructions))}
+                `);
+        case 'USE SEARCH ENGINE':
+            return spaceTrim$1((block) => `
+                    Tool:
+                    - You have access to the web search engine via the tool "web_search".
+                    - Use it to find up-to-date information or facts that you don't know.
+                    - When you need to know some information from the internet, use the tool provided to you.
+                    - Do not make up information when you can search for it.
+                    - Do not tell the user you cannot search for information, YOU CAN.
+                    ${block(formatOptionalInstructionBlock('Search instructions', combinedAdditionalInstructions))}
+                `);
+    }
+}
+/**
+ * Adds the placeholder for an aggregated `USE` system-message section only once, preserving the section position from the first occurrence.
+ *
+ * @param requirements - Current model requirements.
+ * @param type - Aggregated `USE` commitment type being applied.
+ * @returns Requirements with the placeholder inserted when it was not already present.
+ * @private internal utility of `USE` commitments
+ */
+function appendAggregatedUseCommitmentPlaceholder(requirements, type) {
+    const placeholder = getAggregatedUseCommitmentPlaceholder(type);
+    if (requirements.systemMessage.includes(placeholder)) {
+        return requirements;
+    }
+    const systemMessage = requirements.systemMessage.trim()
+        ? `${requirements.systemMessage}\n\n${placeholder}`
+        : placeholder;
+    return {
+        ...requirements,
+        systemMessage,
+    };
+}
+/**
+ * Replaces temporary `USE` placeholders with one aggregated system-message block per commitment type.
+ *
+ * Distinct additional-instruction blocks are merged in stable source order while the hard-coded section is emitted only once.
+ *
+ * @param requirements - Model requirements produced by commitment-by-commitment application.
+ * @param commitments - Filtered commitments in their original source order.
+ * @returns Requirements with aggregated `USE` system-message sections.
+ * @private internal utility of `createAgentModelRequirementsWithCommitments`
+ */
+function aggregateUseCommitmentSystemMessages(requirements, commitments) {
+    const additionalInstructionsByType = new Map();
+    for (const commitment of commitments) {
+        if (!isAggregatedUseCommitmentType(commitment.type)) {
+            continue;
+        }
+        let additionalInstructions = additionalInstructionsByType.get(commitment.type);
+        if (!additionalInstructions) {
+            additionalInstructions = [];
+            additionalInstructionsByType.set(commitment.type, additionalInstructions);
+        }
+        const normalizedContent = spaceTrim$1(commitment.content);
+        if (normalizedContent && !additionalInstructions.includes(normalizedContent)) {
+            additionalInstructions.push(normalizedContent);
+        }
+    }
+    let systemMessage = requirements.systemMessage;
+    for (const [type, additionalInstructions] of additionalInstructionsByType) {
+        const placeholder = getAggregatedUseCommitmentPlaceholder(type);
+        if (!systemMessage.includes(placeholder)) {
+            continue;
+        }
+        systemMessage = systemMessage.replace(placeholder, createAggregatedUseCommitmentSystemMessage(type, additionalInstructions));
+    }
+    return {
+        ...requirements,
+        systemMessage,
+    };
+}
+
 /**
  * Client-side safe wrapper for fetching URL content
  *
@@ -19233,13 +19374,14 @@ async function fetchUrlContentViaBrowser(url, agentsServerUrl) {
  * 1. One-shot URL fetching: Simple function to fetch and scrape URL content
  * 2. Running browser: For complex tasks like scrolling, clicking, form filling, etc.
  *
- * The content following `USE BROWSER` is ignored (similar to NOTE).
+ * The content following `USE BROWSER` is an arbitrary text that the agent should know
+ * (e.g. browsing scope or preferred sources).
  *
  * Example usage in agent source:
  *
  * ```book
  * USE BROWSER
- * USE BROWSER This will be ignored
+ * USE BROWSER Prefer official documentation and source websites.
  * ```
  *
  * @private [🪔] Maybe export the commitments through some package
@@ -19277,7 +19419,7 @@ class UseBrowserCommitmentDefinition extends BaseCommitmentDefinition {
 
             ## Key aspects
 
-            - The content following \`USE BROWSER\` is ignored (similar to NOTE)
+            - The content following \`USE BROWSER\` is an arbitrary text that the agent should know (e.g. browsing scope or preferred sources).
             - Provides two levels of browser access:
               1. **One-shot URL fetching**: Simple function to fetch and scrape URL content (active)
               2. **Running browser**: For complex tasks like scrolling, clicking, form filling, etc. (runtime-dependent)
@@ -19394,20 +19536,14 @@ class UseBrowserCommitmentDefinition extends BaseCommitmentDefinition {
             });
         }
         const updatedTools = [...existingTools, ...toolsToAdd];
-        // Return requirements with updated tools and metadata
-        return this.appendToSystemMessage({
+        return appendAggregatedUseCommitmentPlaceholder({
             ...requirements,
             tools: updatedTools,
             _metadata: {
                 ...requirements._metadata,
                 useBrowser: true,
             },
-        }, spaceTrim$1(`
-                You have access to browser tools to fetch and access content from the internet.
-                - Use "fetch_url_content" to retrieve content from specific URLs (webpages or documents) using scrapers.
-                - Use "run_browser" for real interactive browser automation (navigation, clicks, typing, waiting, scrolling).
-                When you need to know information from a specific website or document, use the fetch_url_content tool.
-            `));
+        }, this.type);
     }
     /**
      * Gets the browser tool function implementations.
@@ -23194,7 +23330,6 @@ class UseSearchEngineCommitmentDefinition extends BaseCommitmentDefinition {
         `);
     }
     applyToAgentModelRequirements(requirements, content) {
-        const extraInstructions = formatOptionalInstructionBlock('Search instructions', content);
         // Get existing tools array or create new one
         const existingTools = requirements.tools || [];
         // Add 'web_search' to tools if not already present
@@ -23207,7 +23342,6 @@ class UseSearchEngineCommitmentDefinition extends BaseCommitmentDefinition {
                     description: spaceTrim$1(`
                         Search the internet for information.
                         Use this tool when you need to find up-to-date information or facts that you don't know.
-                        ${!content ? '' : `Search scope / instructions: ${content}`}
                     `),
                     parameters: {
                         type: 'object',
@@ -23245,23 +23379,14 @@ class UseSearchEngineCommitmentDefinition extends BaseCommitmentDefinition {
                     },
                 },
             ];
-        // Return requirements with updated tools and metadata
-        return this.appendToSystemMessage({
+        return appendAggregatedUseCommitmentPlaceholder({
             ...requirements,
             tools: updatedTools,
             _metadata: {
                 ...requirements._metadata,
                 useSearchEngine: content || true,
             },
-        }, spaceTrim$1((block) => `
-                    Tool:
-                    - You have access to the web search engine via the tool "web_search".
-                    - Use it to find up-to-date information or facts that you don't know.
-                    - When you need to know some information from the internet, use the tool provided to you.
-                    - Do not make up information when you can search for it.
-                    - Do not tell the user you cannot search for information, YOU CAN.
-                    ${block(extraInstructions)}
-            `));
+        }, this.type);
     }
     /**
      * Gets human-readable titles for tool functions provided by this commitment.
@@ -24372,7 +24497,6 @@ class UseTimeCommitmentDefinition extends BaseCommitmentDefinition {
         `);
     }
     applyToAgentModelRequirements(requirements, content) {
-        const extraInstructions = formatOptionalInstructionBlock('Time instructions', content);
         // Get existing tools array or create new one
         const existingTools = requirements.tools || [];
         // Add 'get_current_time' to tools if not already present
@@ -24396,19 +24520,13 @@ class UseTimeCommitmentDefinition extends BaseCommitmentDefinition {
                 },
                 // <- TODO: !!!! define the function in LLM tools
             ];
-        // Return requirements with updated tools and metadata
-        return this.appendToSystemMessage({
+        return appendAggregatedUseCommitmentPlaceholder({
             ...requirements,
             tools: updatedTools,
             _metadata: {
                 ...requirements._metadata,
             },
-        }, spaceTrim$1((block) => `
-                    Time and date context:
-                    - It is ${moment().format('MMMM YYYY')} now.
-                    - If you need more precise current time information, use the tool "get_current_time".
-                    ${block(extraInstructions)}
-                `));
+        }, this.type);
     }
     /**
      * Gets human-readable titles for tool functions provided by this commitment.
@@ -28064,6 +28182,7 @@ async function createAgentModelRequirementsWithCommitments(agentSource, modelNam
             }
         }
     }
+    requirements = aggregateUseCommitmentSystemMessages(requirements, filteredCommitments);
     // Handle IMPORT commitments for generic files
     // Note: This logic could be moved to ImportCommitmentDefinition, but it needs to be asynchronous
     if (requirements.importedFileUrls && requirements.importedFileUrls.length > 0) {