@promptbook/core 0.112.0-47 → 0.112.0-48

package/esm/index.es.js

@@ -10,7 +10,7 @@ import { lookup, extension } from 'mime-types';
 import { parse, unparse } from 'papaparse';
 import moment from 'moment';
 import colors from 'colors';
-import { Agent as Agent$1, setDefaultOpenAIClient, setDefaultOpenAIKey, fileSearchTool, tool, run } from '@openai/agents';
+import { Agent as Agent$1, setDefaultOpenAIClient, setDefaultOpenAIKey, fileSearchTool, tool, run, webSearchTool } from '@openai/agents';
 import Bottleneck from 'bottleneck';
 import OpenAI from 'openai';
 
@@ -28,7 +28,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.112.0-47';
+const PROMPTBOOK_ENGINE_VERSION = '0.112.0-48';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -15651,6 +15651,7 @@ class TemplateCommitmentDefinition extends BaseCommitmentDefinition {
  * Supported USE types:
  * - USE BROWSER: Enables the agent to use a web browser tool
  * - USE SEARCH ENGINE (future): Enables search engine access
+ * - USE DEEPSEARCH: Enables deeper research-oriented search access
  * - USE FILE SYSTEM (future): Enables file system operations
  * - USE MCP (future): Enables MCP server connections
  *
@@ -15673,7 +15674,7 @@ class UseCommitmentDefinition extends BaseCommitmentDefinition {
      * Short one-line description of USE commitments.
      */
     get description() {
-        return 'Enable the agent to use specific tools or capabilities (BROWSER, SEARCH ENGINE, etc.).';
+        return 'Enable the agent to use specific tools or capabilities (BROWSER, SEARCH ENGINE, DEEPSEARCH, etc.).';
     }
     /**
      * Icon for this commitment.
@@ -15694,6 +15695,7 @@ class UseCommitmentDefinition extends BaseCommitmentDefinition {
 
             - **USE BROWSER** - Enables the agent to use a web browser tool to access and retrieve information from the internet
             - **USE SEARCH ENGINE** (future) - Enables search engine access
+            - **USE DEEPSEARCH** - Enables deeper research-oriented search access
             - **USE FILE SYSTEM** (future) - Enables file system operations
             - **USE MCP** (future) - Enables MCP server connections
 
@@ -15748,7 +15750,7 @@ class UseCommitmentDefinition extends BaseCommitmentDefinition {
      * Checks if this is a known USE type
      */
     isKnownUseType(useType) {
-        const knownTypes = ['BROWSER', 'SEARCH ENGINE', 'FILE SYSTEM', 'MCP'];
+        const knownTypes = ['BROWSER', 'SEARCH ENGINE', 'DEEPSEARCH', 'FILE SYSTEM', 'MCP'];
         return knownTypes.includes(useType.toUpperCase());
     }
 }
@@ -15761,6 +15763,7 @@ class UseCommitmentDefinition extends BaseCommitmentDefinition {
  */
 const AGGREGATED_USE_COMMITMENT_TYPES = [
     'USE BROWSER',
+    'USE DEEPSEARCH',
     'USE SEARCH ENGINE',
     'USE TIME',
 ];
@@ -15840,6 +15843,15 @@ function createAggregatedUseCommitmentSystemMessage(type, additionalInstructions
                     - Do not tell the user you cannot search for information, YOU CAN.
                     ${block(formatOptionalInstructionBlock('Search instructions', combinedAdditionalInstructions))}
                 `);
+        case 'USE DEEPSEARCH':
+            return spaceTrim$1((block) => `
+                    Tool:
+                    - You have access to DeepSearch via the tool "deep_search".
+                    - Use it for broader research tasks that need multi-step investigation, comparison, or synthesis across multiple sources.
+                    - Prefer it over quick search when the user asks for a well-grounded brief, report, or deeper investigation.
+                    - Do not pretend you cannot research current information when this tool is available.
+                    ${block(formatOptionalInstructionBlock('DeepSearch instructions', combinedAdditionalInstructions))}
+                `);
     }
 }
 /**
@@ -17389,6 +17401,207 @@ function addConfiguredCalendarIfMissing(configuredCalendars, calendarReference)
 }
 // Note: [💞] Ignore a discrepancy between file name and entity name
 
+/**
+ * A search engine implementation that uses the SerpApi to fetch Google search results.
+ *
+ * @private <- TODO: !!!! Export via some package
+ */
+class SerpSearchEngine {
+    get title() {
+        return 'SerpApi Search Engine';
+    }
+    get description() {
+        return 'Search engine that uses SerpApi to fetch Google search results';
+    }
+    checkConfiguration() {
+        if (!process.env.SERP_API_KEY) {
+            throw new Error('SERP_API_KEY is not configured');
+        }
+    }
+    async search(query, options = {}) {
+        const apiKey = process.env.SERP_API_KEY;
+        if (!apiKey) {
+            throw new Error('SERP_API_KEY is not configured');
+        }
+        const url = new URL('https://serpapi.com/search');
+        url.searchParams.set('api_key', apiKey);
+        url.searchParams.set('engine', 'google');
+        url.searchParams.set('q', query);
+        for (const [key, value] of Object.entries(options)) {
+            url.searchParams.set(key, String(value));
+        }
+        const response = await fetch(url.toString());
+        if (!response.ok) {
+            const body = await response.text();
+            throw new Error(`SerpApi failed with status ${response.status}: ${response.statusText}\n${body}`);
+        }
+        const data = (await response.json());
+        return (data.organic_results || []).map((item) => ({
+            title: item.title,
+            url: item.link,
+            snippet: item.snippet || '',
+        }));
+    }
+}
+
+/**
+ * Creates one SERP-backed tool function used as a local fallback for search-like commitments.
+ *
+ * @param toolName - Technical tool name used for validation messages.
+ * @param resultLabel - Human-readable label used in formatted results.
+ * @returns Async tool function compatible with commitment tool registration.
+ *
+ * @private internal helper for search-like commitments
+ */
+function createSerpSearchToolFunction(toolName, resultLabel) {
+    return async (rawArgs) => {
+        const { query, ...searchOptions } = rawArgs;
+        if (typeof query !== 'string' || !query.trim()) {
+            throw new Error(`${toolName} query is required`);
+        }
+        const searchEngine = new SerpSearchEngine();
+        const results = await searchEngine.search(query, searchOptions);
+        return spaceTrim$1((block) => `
+                ${resultLabel} results for "${query}"${Object.keys(searchOptions).length === 0
+            ? ''
+            : ` with options ${JSON.stringify(searchOptions)}`}:
+
+                ${block(results
+            .map((result) => spaceTrim$1(`
+                                - **${result.title}**
+                                  ${result.url}
+                                  ${result.snippet}
+                            `))
+            .join('\n\n'))}
+            `);
+    };
+}
+
+/**
+ * USE DEEPSEARCH commitment definition
+ *
+ * The `USE DEEPSEARCH` commitment indicates that the agent should use a deeper research-oriented
+ * search workflow instead of lightweight web search when it needs fresh information from the internet.
+ *
+ * The content following `USE DEEPSEARCH` is an arbitrary text that the agent should know
+ * (e.g. search scope or research instructions).
+ *
+ * Example usage in agent source:
+ *
+ * ```book
+ * USE DEEPSEARCH
+ * USE DEEPSEARCH Compare official vendor documentation with independent benchmarks.
+ * ```
+ *
+ * @private [🪔] Maybe export the commitments through some package
+ */
+class UseDeepSearchCommitmentDefinition extends BaseCommitmentDefinition {
+    constructor() {
+        super('USE DEEPSEARCH');
+    }
+    get requiresContent() {
+        return false;
+    }
+    /**
+     * Short one-line description of USE DEEPSEARCH.
+     */
+    get description() {
+        return 'Enable the agent to use DeepSearch for more thorough internet research.';
+    }
+    /**
+     * Icon for this commitment.
+     */
+    get icon() {
+        return '🔬';
+    }
+    /**
+     * Markdown documentation for USE DEEPSEARCH commitment.
+     */
+    get documentation() {
+        return spaceTrim$1(`
+            # USE DEEPSEARCH
+
+            Enables the agent to use DeepSearch for broader, more thorough internet research than lightweight web search.
+
+            ## Key aspects
+
+            - The content following \`USE DEEPSEARCH\` is arbitrary guidance for the research workflow.
+            - In Agents Server, the OpenAI Agents SDK runtime uses a nested deep-research agent for this tool.
+            - Use this for investigations, comparisons, market scans, or other tasks that benefit from deeper synthesis.
+            - Prefer regular \`USE SEARCH ENGINE\` when a quick factual lookup is enough.
+
+            ## Examples
+
+            \`\`\`book
+            Due Diligence Researcher
+
+            GOAL Investigate vendors thoroughly before making recommendations.
+            USE DEEPSEARCH Compare official sources with credible third-party analysis.
+            RULE Cite the strongest supporting sources in the final answer.
+            \`\`\`
+
+            \`\`\`book
+            Market Analyst
+
+            GOAL Build concise but well-grounded research briefs.
+            USE DEEPSEARCH Focus on recent public information and competing viewpoints.
+            CLOSED
+            \`\`\`
+        `);
+    }
+    applyToAgentModelRequirements(requirements, content) {
+        const existingTools = requirements.tools || [];
+        const updatedTools = existingTools.some((tool) => tool.name === 'deep_search')
+            ? existingTools
+            : [
+                ...existingTools,
+                {
+                    name: 'deep_search',
+                    description: spaceTrim$1(`
+                          Research the internet deeply and synthesize a grounded answer.
+                          Use this tool for broader investigations, comparisons, and requests that need more than a quick search.
+                      `),
+                    parameters: {
+                        type: 'object',
+                        properties: {
+                            query: {
+                                type: 'string',
+                                description: 'The research question or investigation request.',
+                            },
+                        },
+                        required: ['query'],
+                        additionalProperties: false,
+                    },
+                },
+            ];
+        return appendAggregatedUseCommitmentPlaceholder({
+            ...requirements,
+            tools: updatedTools,
+            _metadata: {
+                ...requirements._metadata,
+                useDeepSearch: content || true,
+            },
+        }, this.type);
+    }
+    /**
+     * Gets human-readable titles for tool functions provided by this commitment.
+     */
+    getToolTitles() {
+        return {
+            deep_search: 'DeepSearch',
+        };
+    }
+    /**
+     * Gets the local fallback implementation for the `deep_search` tool.
+     */
+    getToolFunctions() {
+        return {
+            deep_search: createSerpSearchToolFunction('deep_search', 'DeepSearch'),
+        };
+    }
+}
+// Note: [💞] Ignore a discrepancy between file name and entity name
+
 /**
  * Lightweight email token matcher used for `USE EMAIL` first-line parsing.
  *
@@ -19776,49 +19989,6 @@ function addConfiguredProjectIfMissing(configuredProjects, repositoryReference)
 }
 // Note: [💞] Ignore a discrepancy between file name and entity name
 
-/**
- * A search engine implementation that uses the SerpApi to fetch Google search results.
- *
- * @private <- TODO: !!!! Export via some package
- */
-class SerpSearchEngine {
-    get title() {
-        return 'SerpApi Search Engine';
-    }
-    get description() {
-        return 'Search engine that uses SerpApi to fetch Google search results';
-    }
-    checkConfiguration() {
-        if (!process.env.SERP_API_KEY) {
-            throw new Error('SERP_API_KEY is not configured');
-        }
-    }
-    async search(query, options = {}) {
-        const apiKey = process.env.SERP_API_KEY;
-        if (!apiKey) {
-            throw new Error('SERP_API_KEY is not configured');
-        }
-        const url = new URL('https://serpapi.com/search');
-        url.searchParams.set('api_key', apiKey);
-        url.searchParams.set('engine', 'google');
-        url.searchParams.set('q', query);
-        for (const [key, value] of Object.entries(options)) {
-            url.searchParams.set(key, String(value));
-        }
-        const response = await fetch(url.toString());
-        if (!response.ok) {
-            const body = await response.text();
-            throw new Error(`SerpApi failed with status ${response.status}: ${response.statusText}\n${body}`);
-        }
-        const data = (await response.json());
-        return (data.organic_results || []).map((item) => ({
-            title: item.title,
-            url: item.link,
-            snippet: item.snippet || '',
-        }));
-    }
-}
-
 /**
  * USE SEARCH ENGINE commitment definition
  *
@@ -19962,26 +20132,7 @@ class UseSearchEngineCommitmentDefinition extends BaseCommitmentDefinition {
      */
     getToolFunctions() {
         return {
-            async web_search(args) {
-                console.log('!!!! [Tool] web_search called', { args });
-                const { query, ...options } = args;
-                if (!query) {
-                    throw new Error('Search query is required');
-                }
-                const searchEngine = new SerpSearchEngine();
-                const results = await searchEngine.search(query, options);
-                return spaceTrim$1((block) => `
-                        Search results for "${query}"${Object.keys(options).length === 0 ? '' : ` with options ${JSON.stringify(options)}`}:
-
-                        ${block(results
-                    .map((result) => spaceTrim$1(`
-                                            - **${result.title}**
-                                              ${result.url}
-                                              ${result.snippet}
-                                        `))
-                    .join('\n\n'))}
-                    `);
-            },
+            web_search: createSerpSearchToolFunction('web_search', 'Search'),
         };
     }
 }
@@ -21627,6 +21778,7 @@ const COMMITMENT_REGISTRY = [
     new ClosedCommitmentDefinition(),
     new TeamCommitmentDefinition(),
     new UseBrowserCommitmentDefinition(),
+    new UseDeepSearchCommitmentDefinition(),
     new UseSearchEngineCommitmentDefinition(),
     new UseSpawnCommitmentDefinition(),
     new UseTimeoutCommitmentDefinition(),
@@ -22796,6 +22948,11 @@ const SIMPLE_CAPABILITY_BY_COMMITMENT_TYPE = {
         label: 'Internet',
         iconName: 'Search',
     },
+    'USE DEEPSEARCH': {
+        type: 'search-engine',
+        label: 'DeepSearch',
+        iconName: 'Search',
+    },
     'USE TIME': {
         type: 'time',
         label: 'Time',
@@ -32845,6 +33002,14 @@ class OpenAiVectorStoreHandler extends OpenAiExecutionTools {
  * Constant for default agent kit model name.
  */
 const DEFAULT_AGENT_KIT_MODEL_NAME = 'gpt-5.4-mini';
+/**
+ * Default model used for nested DeepSearch tool invocations.
+ */
+const DEFAULT_DEEP_SEARCH_MODEL_NAME = 'o4-mini-deep-research';
+/**
+ * Tool name used by the Book commitment-backed DeepSearch capability.
+ */
+const DEEP_SEARCH_TOOL_NAME = 'deep_search';
 /**
  * Creates one structured log entry for streamed tool-call updates.
  *
@@ -32887,6 +33052,98 @@ function resolveFinalToolCallState$1(options) {
     }
     return 'COMPLETE';
 }
+/**
+ * Returns true when one tool definition represents the dedicated DeepSearch capability.
+ *
+ * @param toolDefinition - Tool definition from compiled model requirements.
+ * @returns `true` when the tool should be backed by a nested deep-research agent.
+ *
+ * @private helper of `OpenAiAgentKitExecutionTools`
+ */
+function isDeepSearchToolDefinition(toolDefinition) {
+    return toolDefinition.name === DEEP_SEARCH_TOOL_NAME;
+}
+/**
+ * Normalizes Promptbook JSON-schema tool parameters for AgentKit function tools.
+ *
+ * @param parameters - Promptbook tool parameters.
+ * @returns AgentKit-compatible JSON schema or `undefined`.
+ *
+ * @private helper of `OpenAiAgentKitExecutionTools`
+ */
+function normalizeAgentKitToolParameters(parameters) {
+    var _a, _b;
+    if (!parameters) {
+        return undefined;
+    }
+    return {
+        ...parameters,
+        additionalProperties: (_a = parameters.additionalProperties) !== null && _a !== void 0 ? _a : false,
+        required: (_b = parameters.required) !== null && _b !== void 0 ? _b : [],
+    };
+}
+/**
+ * Creates instructions for the nested DeepSearch specialist agent.
+ *
+ * @param toolDescription - Model-facing description from the original tool definition.
+ * @returns System instructions for the nested deep-research agent.
+ *
+ * @private helper of `OpenAiAgentKitExecutionTools`
+ */
+function createDeepSearchAgentInstructions(toolDescription) {
+    const normalizedDescription = toolDescription.trim();
+    return spaceTrim$1((block) => `
+            You are a DeepSearch specialist working as a tool for another agent.
+            Perform thorough, source-grounded public-web research based on the provided request.
+            Use web search to gather current information, compare relevant viewpoints, and synthesize a concise research brief.
+            Do not ask follow-up questions. If the request is not specific enough, state the assumptions you had to make.
+            Include citations in the research brief whenever sources were used.
+            ${block(normalizedDescription ? `Tool guidance:\n${normalizedDescription}` : '')}
+        `);
+}
+/**
+ * Builds the nested DeepSearch prompt from structured tool arguments.
+ *
+ * @param rawInput - Parsed function-tool arguments provided by the outer agent.
+ * @returns Prompt text passed to the nested deep-research agent.
+ *
+ * @private helper of `OpenAiAgentKitExecutionTools`
+ */
+function buildDeepSearchToolInput(rawInput) {
+    const input = rawInput && typeof rawInput === 'object' ? rawInput : {};
+    const query = typeof input.query === 'string' ? input.query.trim() : '';
+    const additionalHints = Object.entries(input)
+        .filter(([key, value]) => key !== 'query' && value !== undefined && value !== null && String(value).trim() !== '')
+        .map(([key, value]) => `- ${key}: ${typeof value === 'string' ? value : JSON.stringify(value)}`);
+    return spaceTrim$1((block) => `
+            Research request:
+            ${query || JSON.stringify(input)}
+            ${block(additionalHints.length > 0 ? `Execution hints:\n${additionalHints.join('\n')}` : '')}
+        `);
+}
+/**
+ * Creates the native Agent SDK tool used for `USE DEEPSEARCH`.
+ *
+ * @param toolDefinition - Promptbook tool definition for `deep_search`.
+ * @returns AgentKit tool backed by a nested deep-research agent.
+ *
+ * @private helper of `OpenAiAgentKitExecutionTools`
+ */
+function createDeepSearchAgentKitTool(toolDefinition) {
+    const deepSearchAgent = new Agent$1({
+        name: 'DeepSearch',
+        model: DEFAULT_DEEP_SEARCH_MODEL_NAME,
+        instructions: createDeepSearchAgentInstructions(toolDefinition.description),
+        tools: [webSearchTool({ searchContextSize: 'high' })],
+    });
+    return deepSearchAgent.asTool({
+        toolName: toolDefinition.name,
+        toolDescription: toolDefinition.description,
+        parameters: normalizeAgentKitToolParameters(toolDefinition.parameters),
+        inputBuilder: ({ params }) => buildDeepSearchToolInput(params),
+        customOutputExtractor: (result) => { var _a; return typeof result.finalOutput === 'string' ? result.finalOutput : JSON.stringify((_a = result.finalOutput) !== null && _a !== void 0 ? _a : ''); },
+    });
+}
 /**
  * Constant for default JSON schema name.
  */
@@ -33227,25 +33484,23 @@ class OpenAiAgentKitExecutionTools extends OpenAiVectorStoreHandler {
      * Builds the tool list for AgentKit, including hosted file search when applicable.
      */
     buildAgentKitTools(options) {
-        var _a;
         const { tools, vectorStoreId } = options;
         const agentKitTools = [];
         if (vectorStoreId) {
             agentKitTools.push(fileSearchTool(vectorStoreId));
         }
         if (tools && tools.length > 0) {
-            const scriptTools = this.resolveScriptTools();
+            let scriptTools = null;
             for (const toolDefinition of tools) {
+                if (isDeepSearchToolDefinition(toolDefinition)) {
+                    agentKitTools.push(createDeepSearchAgentKitTool(toolDefinition));
+                    continue;
+                }
+                scriptTools !== null && scriptTools !== void 0 ? scriptTools : (scriptTools = this.resolveScriptTools());
                 agentKitTools.push(tool({
                     name: toolDefinition.name,
                     description: toolDefinition.description,
-                    parameters: toolDefinition.parameters
-                        ? {
-                            ...toolDefinition.parameters,
-                            additionalProperties: false,
-                            required: (_a = toolDefinition.parameters.required) !== null && _a !== void 0 ? _a : [],
-                        }
-                        : undefined,
+                    parameters: normalizeAgentKitToolParameters(toolDefinition.parameters),
                     strict: false,
                     execute: async (input, runContext, details) => {
                         var _a, _b, _c, _d;