@promptbook/cli 0.114.0-2 → 0.114.0-20

package/src/commitments/USE_BROWSER/USE_BROWSER.ts

@@ -1,257 +0,0 @@
-import { spaceTrim } from 'spacetrim';
-import type { AgentModelRequirements } from '../../book-2.0/agent-source/AgentModelRequirements';
-import type { ToolFunction } from '../../scripting/javascript/JavascriptExecutionToolsOptions';
-import type { LlmToolDefinition } from '../../types/LlmToolDefinition';
-import type { string_javascript_name } from '../../types/string_person_fullname';
-import type { TODO_any } from '../../utils/organization/TODO_any';
-import { appendAggregatedUseCommitmentPlaceholder } from '../USE/aggregateUseCommitmentSystemMessages';
-import { BaseCommitmentDefinition } from '../_base/BaseCommitmentDefinition';
-import { fetchUrlContentViaBrowser } from './fetchUrlContentViaBrowser';
-
-/**
- * USE BROWSER commitment definition
- *
- * The `USE BROWSER` commitment indicates that the agent should utilize browser tools
- * to access and retrieve up-to-date information from the internet when necessary.
- *
- * This commitment provides two levels of browser access:
- * 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 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 Prefer official documentation and source websites.
- * ```
- *
- * @private [🪔] Maybe export the commitments through some package
- */
-export class UseBrowserCommitmentDefinition extends BaseCommitmentDefinition<'USE BROWSER'> {
-    public constructor() {
-        super('USE BROWSER', ['BROWSER']);
-    }
-
-    /**
-     * The `USE BROWSER` commitment is standalone.
-     */
-    override get requiresContent(): boolean {
-        return false;
-    }
-
-    /**
-     * Short one-line description of USE BROWSER.
-     */
-    get description(): string {
-        return 'Enable the agent to use browser tools for accessing internet information.';
-    }
-
-    /**
-     * Icon for this commitment.
-     */
-    get icon(): string {
-        return '🌐';
-    }
-
-    /**
-     * Markdown documentation for USE BROWSER commitment.
-     */
-    get documentation(): string {
-        return spaceTrim(`
-            # USE BROWSER
-
-            Enables the agent to use browser tools to access and retrieve up-to-date information from the internet.
-
-            ## Key aspects
-
-            - 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)
-            - The actual browser tool usage is handled by the agent runtime
-            - On the Agents Server, every agent browses in its own persistent isolated browser profile, so cookies and logged-in sessions survive across chats (the profile is linked from the agent wallet)
-            - Allows the agent to fetch current information from websites and documents
-            - Useful for research tasks, fact-checking, and accessing dynamic content
-            - Supports various content types including HTML pages and PDF documents
-
-            ## Examples
-
-            \`\`\`book
-            Research Assistant
-
-            PERSONA You are a helpful research assistant specialized in finding current information
-            USE BROWSER
-            RULE Always cite your sources when providing information from the web
-            \`\`\`
-
-            \`\`\`book
-            News Analyst
-
-            PERSONA You are a news analyst who stays up-to-date with current events
-            USE BROWSER
-            WRITING RULES Present news in a balanced and objective manner
-            ACTION Can search for and summarize news articles
-            \`\`\`
-
-            \`\`\`book
-            Company Lawyer
-
-            PERSONA You are a company lawyer providing legal advice
-            USE BROWSER
-            KNOWLEDGE Corporate law and legal procedures
-            RULE Always recommend consulting with a licensed attorney for specific legal matters
-            \`\`\`
-        `);
-    }
-
-    /**
-     * Gets human-readable titles for tool functions provided by this commitment.
-     */
-    getToolTitles(): Record<string_javascript_name, string> {
-        return {
-            fetch_url_content: 'Fetch URL content',
-            run_browser: 'Run browser',
-        };
-    }
-
-    applyToAgentModelRequirements(requirements: AgentModelRequirements, content: string): AgentModelRequirements {
-        // Additional instructions are aggregated later in the final USE system-message pass.
-        void content;
-
-        // Get existing tools array or create new one
-        const existingTools = requirements.tools || [];
-
-        // Add browser tools if not already present
-        const toolsToAdd: Array<LlmToolDefinition> = [];
-
-        // Tool 1: One-shot URL content fetching
-        if (!existingTools.some((tool) => tool.name === 'fetch_url_content')) {
-            toolsToAdd.push({
-                name: 'fetch_url_content',
-                description: spaceTrim(`
-                    Fetches and scrapes the content from a URL (webpage or document).
-                    This tool retrieves the content of the specified URL and converts it to markdown format.
-                    Use this when you need to access information from a specific website or document.
-                    Supports various content types including HTML pages and PDF documents.
-                `),
-                parameters: {
-                    type: 'object',
-                    properties: {
-                        url: {
-                            type: 'string',
-                            description:
-                                'The URL to fetch and scrape (e.g., "https://example.com" or "https://example.com/document.pdf")',
-                        },
-                    },
-                    required: ['url'],
-                },
-            } as TODO_any);
-        }
-
-        // Tool 2: Running browser for complex page interactions
-        if (!existingTools.some((tool) => tool.name === 'run_browser')) {
-            toolsToAdd.push({
-                name: 'run_browser',
-                description: spaceTrim(`
-                    Launches a browser session for complex interactions.
-                    This tool is for advanced browser automation tasks like scrolling, clicking, form filling, etc.
-                    Use this when simple one-shot URL fetching is not enough.
-                `),
-                parameters: {
-                    type: 'object',
-                    properties: {
-                        url: {
-                            type: 'string',
-                            description: 'The initial URL to navigate to',
-                        },
-                        actions: {
-                            type: 'array',
-                            description: 'Array of actions to perform in the browser',
-                            items: {
-                                type: 'object',
-                                properties: {
-                                    type: {
-                                        type: 'string',
-                                        enum: ['navigate', 'click', 'scroll', 'type', 'wait'],
-                                    },
-                                    selector: {
-                                        type: 'string',
-                                        description: 'CSS selector for the element (for click, type actions)',
-                                    },
-                                    value: {
-                                        type: 'string',
-                                        description: 'Value to type or navigate to',
-                                    },
-                                },
-                            },
-                        },
-                    },
-                    required: ['url'],
-                },
-            } as TODO_any);
-        }
-
-        const updatedTools = [...existingTools, ...toolsToAdd];
-
-        return appendAggregatedUseCommitmentPlaceholder(
-            {
-                ...requirements,
-                tools: updatedTools,
-                _metadata: {
-                    ...requirements._metadata,
-                    useBrowser: true,
-                },
-            },
-            this.type,
-        );
-    }
-
-    /**
-     * Gets the browser tool function implementations.
-     *
-     * This method automatically detects the environment and uses:
-     * - Server-side: Direct scraping via fetchUrlContent (Node.js)
-     * - Browser: Proxy through Agents Server API via fetchUrlContentViaBrowser
-     */
-    getToolFunctions(): Record<string_javascript_name, ToolFunction> {
-        return {
-            /**
-             * @@@
-             *
-             * Note: [🛺] This function has implementation both for browser and node, this is the proxied one for browser
-             */
-            async fetch_url_content(args: { url: string }): Promise<string> {
-                console.log('!!!! [Tool] fetch_url_content called', { args });
-
-                const { url } = args;
-
-                return await fetchUrlContentViaBrowser(url);
-            },
-
-            /**
-             * @@@
-             */
-            async run_browser(args: { url: string; actions?: Array<TODO_any> }): Promise<string> {
-                console.log('!!!! [Tool] run_browser called', { args });
-
-                const { url } = args;
-
-                return spaceTrim(`
-                    # Running browser
-
-                    The running browser tool is not available in this runtime.
-
-                    This environment does not provide the server-side browser automation backend.
-                    In Agents Server Node runtime, this tool is resolved to a Playwright CLI implementation.
-
-                    Requested URL: ${url}
-                `);
-            },
-        };
-    }
-}
-
-// Note: [💞] Ignore a discrepancy between file name and entity name

package/src/commitments/USE_BROWSER/fetchUrlContentViaBrowser.ts

@@ -1,45 +0,0 @@
-/**
- * Client-side safe wrapper for fetching URL content
- *
- * This function proxies requests to the Agents Server API endpoint for scraping,
- * making it safe to use in browser environments.
- *
- * @param url The URL to fetch and scrape
- * @param agentsServerUrl The base URL of the agents server (defaults to current origin)
- * @returns Markdown content from the URL
- *
- * @private internal utility for USE BROWSER commitment
- */
-export async function fetchUrlContentViaBrowser(url: string, agentsServerUrl?: string): Promise<string> {
-    try {
-        // Determine the agents server URL
-        const baseUrl = agentsServerUrl || (typeof window !== 'undefined' ? window.location.origin : '');
-
-        if (!baseUrl) {
-            throw new Error('Agents server URL is required in non-browser environments');
-        }
-
-        // Build the API endpoint URL
-        const apiUrl = new URL('/api/scrape', baseUrl);
-        apiUrl.searchParams.set('url', url);
-
-        // Fetch from the API endpoint
-        const response = await fetch(apiUrl.toString());
-
-        if (!response.ok) {
-            const errorData = await response.json().catch(() => ({ error: 'Unknown error' }));
-            throw new Error(`Failed to scrape URL: ${errorData.error || response.statusText}`);
-        }
-
-        const data = await response.json();
-
-        if (!data.success || !data.content) {
-            throw new Error(`Scraping failed: ${data.error || 'No content returned'}`);
-        }
-
-        return data.content;
-    } catch (error) {
-        const errorMessage = error instanceof Error ? error.message : String(error);
-        throw new Error(`Error fetching URL content via browser: ${errorMessage}`);
-    }
-}

package/src/commitments/USE_BROWSER/resolveRunBrowserToolForNode.ts

@@ -1,83 +0,0 @@
-import { spaceTrim } from 'spacetrim';
-import { assertsError } from '../../errors/assertsError';
-import { EnvironmentMismatchError } from '../../errors/EnvironmentMismatchError';
-import type { ToolFunction } from '../../scripting/javascript/JavascriptExecutionToolsOptions';
-
-/**
- * Cached implementation of `run_browser` when it can be resolved.
- *
- * @private internal utility for USE BROWSER commitment
- */
-let cachedRunBrowserTool: ToolFunction | null = null;
-
-/**
- * Cached loading error to avoid repeating expensive resolution attempts.
- *
- * @private internal utility for USE BROWSER commitment
- */
-let cachedRunBrowserToolError: Error | null = null;
-
-/**
- * Attempts to load the server-side `run_browser` tool lazily.
- *
- * @returns Loaded `run_browser` implementation
- *
- * @private internal utility for USE BROWSER commitment
- */
-function loadRunBrowserToolForNode(): ToolFunction {
-    if (cachedRunBrowserTool !== null) {
-        return cachedRunBrowserTool;
-    }
-
-    if (cachedRunBrowserToolError !== null) {
-        throw cachedRunBrowserToolError;
-    }
-
-    try {
-        // eslint-disable-next-line @typescript-eslint/no-var-requires
-        const runBrowserModule = require('../../../apps/agents-server/src/tools/run_browser') as {
-            run_browser?: unknown;
-        };
-
-        if (typeof runBrowserModule.run_browser !== 'function') {
-            throw new Error('run_browser value is not a function but ' + typeof runBrowserModule.run_browser);
-        }
-
-        cachedRunBrowserTool = runBrowserModule.run_browser as ToolFunction;
-        return cachedRunBrowserTool;
-    } catch (error) {
-        assertsError(error);
-        cachedRunBrowserToolError = error;
-        throw error;
-    }
-}
-
-/**
- * Resolves the server-side implementation of the `run_browser` tool for Node.js environments.
- *
- * This uses fully lazy resolution to keep CLI startup independent from optional browser tooling.
- * When the server tool cannot be resolved, the fallback implementation throws a helpful error.
- *
- * @private internal utility for USE BROWSER commitment
- */
-export function resolveRunBrowserToolForNode(): ToolFunction {
-    return async (args) => {
-        try {
-            const runBrowserTool = loadRunBrowserToolForNode();
-            return await runBrowserTool(args);
-        } catch (error) {
-            assertsError(error);
-            throw new EnvironmentMismatchError(
-                spaceTrim(
-                    (block) => `
-                        \`run_browser\` tool is not available in this environment.
-                        This commitment requires the Agents Server browser runtime with Playwright CLI.
-
-                        ${(error as Error).name}:
-                        ${block((error as Error).message)}
-                    `,
-                ),
-            );
-        }
-    };
-}

package/src/commitments/USE_DEEPSEARCH/USE_DEEPSEARCH.ts

@@ -1,146 +0,0 @@
-import { spaceTrim } from 'spacetrim';
-import type { AgentModelRequirements } from '../../book-2.0/agent-source/AgentModelRequirements';
-import type { ToolFunction } from '../../scripting/javascript/JavascriptExecutionToolsOptions';
-import type { string_javascript_name } from '../../types/string_person_fullname';
-import type { TODO_any } from '../../utils/organization/TODO_any';
-import { appendAggregatedUseCommitmentPlaceholder } from '../USE/aggregateUseCommitmentSystemMessages';
-import { BaseCommitmentDefinition } from '../_base/BaseCommitmentDefinition';
-import { createSerpSearchToolFunction } from '../_common/createSerpSearchToolFunction';
-
-/**
- * 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
- */
-export class UseDeepSearchCommitmentDefinition extends BaseCommitmentDefinition<'USE DEEPSEARCH'> {
-    public constructor() {
-        super('USE DEEPSEARCH');
-    }
-
-    override get requiresContent(): boolean {
-        return false;
-    }
-
-    /**
-     * Short one-line description of USE DEEPSEARCH.
-     */
-    get description(): string {
-        return 'Enable the agent to use DeepSearch for more thorough internet research.';
-    }
-
-    /**
-     * Icon for this commitment.
-     */
-    get icon(): string {
-        return '🔬';
-    }
-
-    /**
-     * Markdown documentation for USE DEEPSEARCH commitment.
-     */
-    get documentation(): string {
-        return spaceTrim(`
-            # 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: AgentModelRequirements, content: string): AgentModelRequirements {
-        const existingTools = requirements.tools || [];
-
-        const updatedTools = existingTools.some((tool) => tool.name === 'deep_search')
-            ? existingTools
-            : [
-                  ...existingTools,
-                  {
-                      name: 'deep_search',
-                      description: spaceTrim(`
-                          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,
-                      },
-                  } as TODO_any,
-              ];
-
-        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(): Record<string_javascript_name, string> {
-        return {
-            deep_search: 'DeepSearch',
-        };
-    }
-
-    /**
-     * Gets the local fallback implementation for the `deep_search` tool.
-     */
-    getToolFunctions(): Record<string_javascript_name, ToolFunction> {
-        return {
-            deep_search: createSerpSearchToolFunction('deep_search', 'DeepSearch'),
-        };
-    }
-}
-
-// Note: [💞] Ignore a discrepancy between file name and entity name