@promptbook/cli 0.114.0-3 → 0.114.0-31

package/src/commitments/META/META.ts

@@ -1,168 +0,0 @@
-import { spaceTrim } from 'spacetrim';
-import type { AgentModelRequirements } from '../../book-2.0/agent-source/AgentModelRequirements';
-import { TODO_USE } from '../../utils/organization/TODO_USE';
-import { BaseCommitmentDefinition } from '../_base/BaseCommitmentDefinition';
-
-/**
- * META commitment definition
- *
- * The META commitment handles all meta-information about the agent such as:
- * - META AVATAR / META VISUAL: Sets the agent's built-in default avatar visual
- * - META IMAGE: Sets the agent's avatar/profile image URL
- * - META LINK: Provides profile/source links for the person the agent models
- * - META DOMAIN: Sets the canonical custom domain/host of the agent
- * - META TITLE: Sets the agent's display title
- * - META DESCRIPTION: Sets the agent's description
- * - META INPUT PLACEHOLDER: Sets chat input placeholder text
- * - META THINKING MESSAGE: Adds custom thinking placeholder variants
- * - META [ANYTHING]: Any other meta information in uppercase format
- *
- * These commitments are special because they don't affect the system message,
- * but are handled separately in the parsing logic for profile display.
- *
- * Example usage in agent source:
- *
- * ```book
- * META VISUAL pixel-art
- * META IMAGE https://example.com/avatar.jpg
- * META LINK https://twitter.com/username
- * META DOMAIN my-agent.com
- * META TITLE Professional Assistant
- * META DESCRIPTION An AI assistant specialized in business tasks
- * META INPUT PLACEHOLDER Write a message...
- * META THINKING MESSAGE Thinking...
- * META AUTHOR John Doe
- * META VERSION 1.0
- * ```
- *
- * @private [🪔] Maybe export the commitments through some package
- */
-export class MetaCommitmentDefinition extends BaseCommitmentDefinition<`META${string}`> {
-    public constructor() {
-        super('META');
-    }
-
-    /**
-     * Short one-line description of META commitments.
-     */
-    get description(): string {
-        return 'Set meta-information about the agent (IMAGE, LINK, TITLE, DESCRIPTION, etc.).';
-    }
-
-    /**
-     * Icon for this commitment.
-     */
-    get icon(): string {
-        return 'ℹ️';
-    }
-
-    /**
-     * Markdown documentation for META commitment.
-     */
-    get documentation(): string {
-        return spaceTrim(`
-            # META
-
-            Sets meta-information about the agent that is used for display and attribution purposes.
-
-            ## Supported META types
-
-            - **META AVATAR** / **META VISUAL** - Sets the agent's built-in default avatar visual
-            - **META IMAGE** - Sets the agent's avatar/profile image URL
-            - **META LINK** - Provides profile/source links for the person the agent models
-            - **META DOMAIN** - Sets the canonical custom domain/host of the agent
-            - **META TITLE** - Sets the agent's display title
-            - **META DESCRIPTION** - Sets the agent's description
-            - **META INPUT PLACEHOLDER** - Sets chat input placeholder text
-            - **META THINKING MESSAGE** - Adds custom thinking placeholder variants
-            - **META [ANYTHING]** - Any other meta information in uppercase format
-
-            ## Key aspects
-
-            - Does not modify the agent's behavior or responses
-            - Used for visual representation and attribution in user interfaces
-            - Multiple META commitments of different types can be used
-            - Multiple META LINK commitments can be used for different social profiles
-            - Multiple META THINKING MESSAGE commitments can be used for different thinking placeholder variants
-            - If multiple META commitments of the same type are specified, the last one takes precedence (except for LINK)
-
-            ## Examples
-
-            ### Basic meta information
-
-            \`\`\`book
-            Professional Assistant
-
-            META VISUAL octopus3
-            META IMAGE https://example.com/professional-avatar.jpg
-            META TITLE Senior Business Consultant
-            META DESCRIPTION Specialized in strategic planning and project management
-            META LINK https://linkedin.com/in/professional
-            \`\`\`
-
-            ### Multiple links and custom meta
-
-            \`\`\`book
-            Open Source Developer
-
-            META IMAGE /assets/dev-avatar.png
-            META LINK https://github.com/developer
-            META LINK https://twitter.com/devhandle
-            META AUTHOR Jane Smith
-            META VERSION 2.1
-            META LICENSE MIT
-            \`\`\`
-
-            ### Creative assistant
-
-            \`\`\`book
-            Creative Helper
-
-            META IMAGE https://example.com/creative-bot.jpg
-            META TITLE Creative Writing Assistant
-            META DESCRIPTION Helps with brainstorming, storytelling, and creative projects
-            META INSPIRATION Books, movies, and real-world experiences
-            \`\`\`
-        `);
-    }
-
-    applyToAgentModelRequirements(requirements: AgentModelRequirements, content: string): AgentModelRequirements {
-        TODO_USE(content);
-
-        // META commitments don't modify the system message or model requirements
-        // They are handled separately in the parsing logic for meta information extraction
-        // This method exists for consistency with the CommitmentDefinition interface
-        return requirements;
-    }
-
-    /**
-     * Extracts meta information from the content based on the meta type
-     * This is used by the parsing logic
-     */
-    extractMetaValue(metaType: string, content: string): string | null {
-        const trimmedContent = content.trim();
-        return trimmedContent || null;
-    }
-
-    /**
-     * Validates if the provided content is a valid URL (for IMAGE and LINK types)
-     */
-    isValidUrl(content: string): boolean {
-        try {
-            new URL(content.trim());
-            return true;
-        } catch {
-            return false;
-        }
-    }
-
-    /**
-     * Checks if this is a known meta type
-     */
-    isKnownMetaType(metaType: string): boolean {
-        const knownTypes = ['AVATAR', 'IMAGE', 'LINK', 'TITLE', 'DESCRIPTION', 'AUTHOR', 'VERSION', 'LICENSE'];
-        return knownTypes.includes(metaType.toUpperCase());
-    }
-}
-
-// Note: [💞] Ignore a discrepancy between file name and entity name

package/src/commitments/USE/TODO.txt

@@ -1 +0,0 @@
-TODO: [🔰] USE commitments are working in demo mode only. Need to implement full functionality.

package/src/commitments/USE/aggregateUseCommitmentSystemMessages.ts

@@ -1,219 +0,0 @@
-import moment from 'moment';
-import { spaceTrim } from 'spacetrim';
-import type { AgentModelRequirements } from '../../book-2.0/agent-source/AgentModelRequirements';
-import type { ParsedCommitment } from '../_base/ParsedCommitment';
-import { formatOptionalInstructionBlock } from '../_base/formatOptionalInstructionBlock';
-
-/**
- * `USE` commitment types whose system-message sections are aggregated after the
- * commitment-by-commitment application step.
- *
- * @private internal utility of `createAgentModelRequirementsWithCommitments`
- */
-type AggregatedUseCommitmentType = 'USE BROWSER' | 'USE DEEPSEARCH' | 'USE SEARCH ENGINE' | 'USE TIME';
-
-/**
- * All `USE` commitment types currently participating in final system-message aggregation.
- *
- * @private internal constant for `aggregateUseCommitmentSystemMessages`
- */
-const AGGREGATED_USE_COMMITMENT_TYPES = [
-    'USE BROWSER',
-    'USE DEEPSEARCH',
-    'USE SEARCH ENGINE',
-    'USE TIME',
-] as const satisfies ReadonlyArray<AggregatedUseCommitmentType>;
-
-/**
- * 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: ParsedCommitment['type']): type is AggregatedUseCommitmentType {
-    return (AGGREGATED_USE_COMMITMENT_TYPES as ReadonlyArray<string>).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: AggregatedUseCommitmentType): string {
-    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: ReadonlyArray<string>): string {
-    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: AggregatedUseCommitmentType,
-    additionalInstructions: ReadonlyArray<string>,
-): string {
-    const combinedAdditionalInstructions = combineAdditionalInstructions(additionalInstructions);
-
-    switch (type) {
-        case 'USE TIME':
-            return spaceTrim(
-                (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(
-                (block) => `
-                    ## Browser
-
-                    -   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 tools provided.
-                    ${block(formatOptionalInstructionBlock('Browser instructions', combinedAdditionalInstructions))}
-                `,
-            );
-
-        case 'USE SEARCH ENGINE':
-            return spaceTrim(
-                (block) => `
-                    ## Web Search
-
-                    -   Use \`web_search\` to find up-to-date information or facts.
-                    -   When you need to know some information from the internet, use the search tool provided.
-                    -   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))}
-                `,
-            );
-
-        case 'USE DEEPSEARCH':
-            return spaceTrim(
-                (block) => `
-                    ## Deep Research
-
-                    -   Use \`deep_search\` 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))}
-                `,
-            );
-    }
-}
-
-/**
- * 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
- */
-export function appendAggregatedUseCommitmentPlaceholder(
-    requirements: AgentModelRequirements,
-    type: AggregatedUseCommitmentType,
-): AgentModelRequirements {
-    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`
- */
-export function aggregateUseCommitmentSystemMessages(
-    requirements: AgentModelRequirements,
-    commitments: ReadonlyArray<ParsedCommitment>,
-): AgentModelRequirements {
-    const additionalInstructionsByType = new Map<AggregatedUseCommitmentType, string[]>();
-
-    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(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,
-    };
-}

package/src/commitments/USE_BROWSER/TODO.txt

@@ -1 +0,0 @@
-TODO: [🔰] USE commitments are working in demo mode only. Need to implement full functionality via MCP

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