@promptbook/cli 0.114.0-2 → 0.114.0-20

package/src/commitments/USE_EMAIL/USE_EMAIL.ts

@@ -1,201 +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 { BaseCommitmentDefinition } from '../_base/BaseCommitmentDefinition';
-import { formatOptionalInstructionBlock } from '../_base/formatOptionalInstructionBlock';
-import { parseUseEmailCommitmentContent } from './parseUseEmailCommitmentContent';
-import { sendEmailViaBrowser } from './sendEmailViaBrowser';
-
-/**
- * Tool name used by USE EMAIL.
- *
- * @private internal USE EMAIL constant
- */
-const SEND_EMAIL_TOOL_NAME = 'send_email' as string_javascript_name;
-
-/**
- * USE EMAIL commitment definition.
- *
- * The `USE EMAIL` commitment enables outbound email sending through the `send_email` tool.
- *
- * @private [🪔] Maybe export the commitments through some package
- */
-export class UseEmailCommitmentDefinition extends BaseCommitmentDefinition<'USE EMAIL'> {
-    public constructor() {
-        super('USE EMAIL', ['EMAIL', 'MAIL']);
-    }
-
-    override get requiresContent(): boolean {
-        return false;
-    }
-
-    /**
-     * Short one-line description of USE EMAIL.
-     */
-    get description(): string {
-        return 'Enable outbound email sending through a wallet-backed SMTP configuration.';
-    }
-
-    /**
-     * Icon for this commitment.
-     */
-    get icon(): string {
-        return '📧';
-    }
-
-    /**
-     * Markdown documentation for USE EMAIL commitment.
-     */
-    get documentation(): string {
-        return spaceTrim(`
-            # USE EMAIL
-
-            Enables the agent to send outbound emails through SMTP.
-
-            ## Key aspects
-
-            - The agent sends email via the \`send_email\` tool.
-            - SMTP credentials are expected from wallet records (\`ACCESS_TOKEN\`, service \`smtp\`, key \`use-email-smtp-credentials\`).
-            - Commitment content can optionally begin with a default sender email address:
-              - \`USE EMAIL agent@example.com\`
-            - Remaining commitment content is treated as optional email-writing instructions.
-
-            ## Examples
-
-            \`\`\`book
-            Writing Agent
-            USE EMAIL agent@example.com
-            RULE Write emails to customers according to the instructions from user.
-            \`\`\`
-
-            \`\`\`book
-            Formal Email Assistant
-            USE EMAIL agent@example.com Keep emails concise and formal.
-            \`\`\`
-        `);
-    }
-
-    applyToAgentModelRequirements(requirements: AgentModelRequirements, content: string): AgentModelRequirements {
-        const parsedCommitment = parseUseEmailCommitmentContent(content);
-        const updatedTools = addUseEmailTools(requirements.tools || []);
-
-        // Collect all configured sender emails across multiple USE EMAIL commitments
-        const existingSenders: string[] = Array.isArray(requirements._metadata?.useEmailSenders)
-            ? [...(requirements._metadata!.useEmailSenders as string[])]
-            : [];
-        if (parsedCommitment.senderEmail && !existingSenders.includes(parsedCommitment.senderEmail)) {
-            existingSenders.push(parsedCommitment.senderEmail);
-        }
-
-        const senderBullets =
-            existingSenders.length > 0
-                ? existingSenders
-                      .map((email, index) =>
-                          index === 0
-                              ? `-   Default sender address: "${email}".`
-                              : `-   Additional sender address: "${email}".`,
-                      )
-                      .join('\n')
-                : '';
-
-        const extraInstructions = formatOptionalInstructionBlock('Email instructions', parsedCommitment.instructions);
-
-        const emailSectionContent = spaceTrim(
-            (block) => `
-                ## Emails
-
-                -   Use \`${SEND_EMAIL_TOOL_NAME}\` to send outbound emails.
-                ${block(senderBullets)}
-                ${block(extraInstructions)}
-            `,
-        );
-
-        return this.replaceOrCreateSection(
-            {
-                ...requirements,
-                tools: updatedTools,
-                _metadata: {
-                    ...requirements._metadata,
-                    useEmail: true,
-                    ...(parsedCommitment.senderEmail ? { useEmailSender: parsedCommitment.senderEmail } : {}),
-                    useEmailSenders: existingSenders,
-                },
-            },
-            'Emails',
-            emailSectionContent,
-        );
-    }
-
-    /**
-     * Gets human-readable titles for tool functions provided by this commitment.
-     */
-    getToolTitles(): Record<string_javascript_name, string> {
-        return {
-            [SEND_EMAIL_TOOL_NAME]: 'Send email',
-        };
-    }
-
-    /**
-     * Gets the browser-safe `send_email` implementation.
-     *
-     * Node.js runtime overrides this via `getAllCommitmentsToolFunctionsForNode`.
-     */
-    getToolFunctions(): Record<string_javascript_name, ToolFunction> {
-        return {
-            async [SEND_EMAIL_TOOL_NAME](args: unknown): Promise<string> {
-                return sendEmailViaBrowser(args as Record<string, unknown>);
-            },
-        };
-    }
-}
-
-/**
- * Adds USE EMAIL tool definition while keeping already registered tools untouched.
- *
- * @private utility of USE EMAIL commitment
- */
-function addUseEmailTools(existingTools: ReadonlyArray<LlmToolDefinition>): Array<LlmToolDefinition> {
-    if (existingTools.some((tool) => tool.name === SEND_EMAIL_TOOL_NAME)) {
-        return [...existingTools];
-    }
-
-    return [
-        ...existingTools,
-        {
-            name: SEND_EMAIL_TOOL_NAME,
-            description: 'Send an outbound email.',
-            parameters: {
-                type: 'object',
-                properties: {
-                    message: {
-                        type: 'object',
-                        description: 'Email payload. Use metadata.subject for the subject line.',
-                    },
-                    to: {
-                        type: 'string',
-                        description:
-                            'Legacy alias for recipients (use comma-separated emails or JSON array encoded as string).',
-                    },
-                    cc: {
-                        type: 'string',
-                        description:
-                            'Optional CC recipients (use comma-separated emails or JSON array encoded as string).',
-                    },
-                    subject: {
-                        type: 'string',
-                        description: 'Legacy alias for subject.',
-                    },
-                    body: {
-                        type: 'string',
-                        description: 'Legacy alias for markdown body content.',
-                    },
-                },
-                required: [],
-            },
-        },
-    ];
-}
-
-// Note: [💞] Ignore a discrepancy between file name and entity name

package/src/commitments/USE_EMAIL/parseUseEmailCommitmentContent.ts

@@ -1,75 +0,0 @@
-import { spaceTrim } from 'spacetrim';
-import { isValidEmail } from '../../utils/validators/email/isValidEmail';
-
-/**
- * Lightweight email token matcher used for `USE EMAIL` first-line parsing.
- *
- * @private internal USE EMAIL constant
- */
-const EMAIL_TOKEN_PATTERN = /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/;
-
-/**
- * Parsed payload of one `USE EMAIL` commitment.
- *
- * @private internal USE EMAIL type
- */
-export type ParsedUseEmailCommitmentContent = {
-    senderEmail: string | null;
-    senderEmailRaw: string | null;
-    instructions: string;
-};
-
-/**
- * Parses `USE EMAIL` commitment content into optional sender email + additional instructions.
- *
- * Examples:
- * - `agent@example.com`
- * - `agent@example.com Keep emails concise`
- * - `Keep emails concise`
- *
- * @private internal utility of USE EMAIL commitment
- */
-export function parseUseEmailCommitmentContent(content: string): ParsedUseEmailCommitmentContent {
-    const trimmedContent = spaceTrim(content);
-    if (!trimmedContent) {
-        return {
-            senderEmail: null,
-            senderEmailRaw: null,
-            instructions: '',
-        };
-    }
-
-    const lines = trimmedContent
-        .split(/\r?\n/)
-        .map((line) => line.trim())
-        .filter(Boolean);
-    if (lines.length === 0) {
-        return {
-            senderEmail: null,
-            senderEmailRaw: null,
-            instructions: '',
-        };
-    }
-
-    const firstLine = lines[0] || '';
-    const senderMatch = firstLine.match(EMAIL_TOKEN_PATTERN);
-    const senderEmailRaw = senderMatch?.[0] || null;
-    const senderEmail = senderEmailRaw && isValidEmail(senderEmailRaw) ? senderEmailRaw : null;
-
-    let firstLineWithoutSender = firstLine;
-    if (senderEmailRaw) {
-        const matchIndex = firstLine.indexOf(senderEmailRaw);
-        const prefix = firstLine.slice(0, matchIndex).trim();
-        const suffix = firstLine.slice(matchIndex + senderEmailRaw.length).trim();
-        firstLineWithoutSender = [prefix, suffix].filter(Boolean).join(' ').trim();
-    }
-
-    const instructionLines = [firstLineWithoutSender, ...lines.slice(1)].filter(Boolean);
-    const instructions = instructionLines.join('\n').trim();
-
-    return {
-        senderEmail,
-        senderEmailRaw,
-        instructions,
-    };
-}

package/src/commitments/USE_EMAIL/resolveSendEmailToolForNode.ts

@@ -1,44 +0,0 @@
-import { spaceTrim } from 'spacetrim';
-import { EnvironmentMismatchError } from '../../errors/EnvironmentMismatchError';
-import type { ToolFunction } from '../../scripting/javascript/JavascriptExecutionToolsOptions';
-
-/**
- * Resolves the server-side implementation of the send_email tool for Node.js environments.
- *
- * This uses a lazy require so the core package can still load even if the Agents Server
- * module is unavailable. When the server tool cannot be resolved, a fallback implementation
- * throws a helpful error message.
- *
- * @private internal utility for USE EMAIL commitment
- */
-export function resolveSendEmailToolForNode(): ToolFunction {
-    try {
-        // eslint-disable-next-line @typescript-eslint/no-var-requires
-        const { send_email } = require('../../../apps/agents-server/src/tools/send_email');
-
-        if (typeof send_email !== 'function') {
-            throw new Error('send_email value is not a function but ' + typeof send_email);
-        }
-
-        return send_email as ToolFunction;
-    } catch (error) {
-        const normalizedError =
-            error instanceof Error
-                ? error
-                : new Error(typeof error === 'string' ? error : JSON.stringify(error ?? 'Unknown error'));
-
-        return async () => {
-            throw new EnvironmentMismatchError(
-                spaceTrim(
-                    (block) => `
-                        \`send_email\` tool is not available in this environment.
-                        This commitment requires Agents Server runtime with wallet-backed SMTP sending.
-
-                        ${normalizedError.name}:
-                        ${block(normalizedError.message)}
-                    `,
-                ),
-            );
-        };
-    }
-}

package/src/commitments/USE_EMAIL/sendEmailViaBrowser.ts

@@ -1,47 +0,0 @@
-/**
- * Client-side safe wrapper for sending emails.
- *
- * This function proxies requests to the Agents Server API endpoint for email queuing,
- * making it safe to use in browser environments.
- *
- * @param args Email payload forwarded to the server-side `send_email` tool
- * @param agentsServerUrl The base URL of the agents server (defaults to current origin)
- * @returns Result string from the server-side send_email tool
- *
- * @private internal utility for USE EMAIL commitment
- */
-export async function sendEmailViaBrowser(args: Record<string, unknown>, agentsServerUrl?: string): Promise<string> {
-    try {
-        const baseUrl = agentsServerUrl || (typeof window !== 'undefined' ? window.location.origin : '');
-
-        if (!baseUrl) {
-            throw new Error('Agents server URL is required in non-browser environments');
-        }
-
-        const apiUrl = new URL('/api/send-email', baseUrl);
-
-        const response = await fetch(apiUrl.toString(), {
-            method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-            },
-            body: JSON.stringify(args),
-        });
-
-        if (!response.ok) {
-            const errorData = await response.json().catch(() => ({ error: 'Unknown error' }));
-            throw new Error(`Failed to send email: ${errorData.error || response.statusText}`);
-        }
-
-        const data = await response.json();
-
-        if (!data.success) {
-            throw new Error(`Email sending failed: ${data.error || 'Unknown error'}`);
-        }
-
-        return typeof data.result === 'string' ? data.result : JSON.stringify(data.result);
-    } catch (error) {
-        const errorMessage = error instanceof Error ? error.message : String(error);
-        throw new Error(`Error sending email via browser: ${errorMessage}`);
-    }
-}

package/src/commitments/USE_SEARCH_ENGINE/TODO.txt

@@ -1 +0,0 @@
-TODO: [🔰] USE SEARCH is working only in demo mode only. Need to implement full functionality via MCP server and Search engines

package/src/commitments/USE_SEARCH_ENGINE/USE_SEARCH_ENGINE.ts

@@ -1,171 +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 SEARCH ENGINE commitment definition
- *
- * The `USE SEARCH ENGINE` commitment indicates that the agent should utilize a search engine tool
- * to access and retrieve up-to-date information from the internet when necessary.
- *
- * The content following `USE SEARCH ENGINE` is an arbitrary text that the agent should know (e.g. search scope or instructions).
- *
- * Example usage in agent source:
- *
- * ```book
- * USE SEARCH ENGINE
- * USE SEARCH ENGINE Hledej informace o Přemyslovcích
- * ```
- *
- * @private [🪔] Maybe export the commitments through some package
- */
-export class UseSearchEngineCommitmentDefinition extends BaseCommitmentDefinition<'USE SEARCH ENGINE'> {
-    public constructor() {
-        super('USE SEARCH ENGINE', ['USE SEARCH']);
-    }
-
-    override get requiresContent(): boolean {
-        return false;
-    }
-
-    /**
-     * Short one-line description of USE SEARCH ENGINE.
-     */
-    get description(): string {
-        return 'Enable the agent to use a search engine tool for accessing internet information.';
-    }
-
-    /**
-     * Icon for this commitment.
-     */
-    get icon(): string {
-        return '🔍';
-    }
-
-    /**
-     * Markdown documentation for USE SEARCH ENGINE commitment.
-     */
-    get documentation(): string {
-        return spaceTrim(`
-            # USE SEARCH ENGINE
-
-            Enables the agent to use a search engine tool to access and retrieve up-to-date information from the internet.
-
-            ## Key aspects
-
-            - The content following \`USE SEARCH ENGINE\` is an arbitrary text that the agent should know (e.g. search scope or instructions).
-            - The actual search engine tool usage is handled by the agent runtime
-            - Allows the agent to search for current information from the web
-            - Useful for research tasks, finding facts, and accessing dynamic content
-
-            ## Examples
-
-            \`\`\`book
-            Research Assistant
-
-            PERSONA You are a helpful research assistant specialized in finding current information
-            USE SEARCH ENGINE
-            RULE Always cite your sources when providing information from the web
-            \`\`\`
-
-            \`\`\`book
-            Fact Checker
-
-            PERSONA You are a fact checker
-            USE SEARCH ENGINE
-            ACTION Search for claims and verify them against reliable sources
-            \`\`\`
-        `);
-    }
-
-    applyToAgentModelRequirements(requirements: AgentModelRequirements, content: string): AgentModelRequirements {
-        // Get existing tools array or create new one
-        const existingTools = requirements.tools || [];
-
-        // Add 'web_search' to tools if not already present
-        const updatedTools = existingTools.some((tool) => tool.name === 'web_search')
-            ? existingTools
-            : [
-                  ...existingTools,
-                  {
-                      name: 'web_search',
-                      description: spaceTrim(`
-                        Search the internet for information.
-                        Use this tool when you need to find up-to-date information or facts that you don't know.
-                    `),
-                      parameters: {
-                          type: 'object',
-                          properties: {
-                              query: {
-                                  type: 'string',
-                                  description: 'The search query',
-                              },
-                              location: {
-                                  type: 'string',
-                                  description:
-                                      'The location for the search (e.g., "Austin, Texas, United States" or "Prague, Czechia")',
-                              },
-                              gl: {
-                                  type: 'string',
-                                  description: 'The country code (e.g., "us" for United States, "cz" for Czechia)',
-                              },
-                              hl: {
-                                  type: 'string',
-                                  description: 'The language code (e.g., "en" for English, "cs" for Czech)',
-                              },
-                              num: {
-                                  type: 'integer',
-                                  description: 'Number of results to return',
-                              },
-                              engine: {
-                                  type: 'string',
-                                  description: 'The search engine to use (e.g., "google", "bing", "yahoo", "baidu")',
-                              },
-                              google_domain: {
-                                  type: 'string',
-                                  description: 'The Google domain to use (e.g., "google.com", "google.cz")',
-                              },
-                          },
-                          required: ['query'],
-                      },
-                  } as TODO_any,
-              ];
-
-        return appendAggregatedUseCommitmentPlaceholder(
-            {
-                ...requirements,
-                tools: updatedTools,
-                _metadata: {
-                    ...requirements._metadata,
-                    useSearchEngine: content || true,
-                },
-            },
-            this.type,
-        );
-    }
-
-    /**
-     * Gets human-readable titles for tool functions provided by this commitment.
-     */
-    getToolTitles(): Record<string_javascript_name, string> {
-        return {
-            web_search: 'Web search',
-        };
-    }
-
-    /**
-     * Gets the `web_search` tool function implementation.
-     */
-    getToolFunctions(): Record<string_javascript_name, ToolFunction> {
-        return {
-            web_search: createSerpSearchToolFunction('web_search', 'Search'),
-        };
-    }
-}
-
-// Note: [💞] Ignore a discrepancy between file name and entity name

package/src/commitments/USE_SPAWN/USE_SPAWN.ts

@@ -1,150 +0,0 @@
-import { spaceTrim } from 'spacetrim';
-import type { AgentModelRequirements } from '../../book-2.0/agent-source/AgentModelRequirements';
-import {
-    createCreateAgentInputToolParametersSchema,
-    CREATE_AGENT_INPUT_SOURCE_MAX_LENGTH,
-} from '../../collection/agent-collection/CreateAgentInput';
-import type { ToolFunction } from '../../scripting/javascript/JavascriptExecutionToolsOptions';
-import type { LlmToolDefinition } from '../../types/LlmToolDefinition';
-import type { string_javascript_name } from '../../types/string_person_fullname';
-import { BaseCommitmentDefinition } from '../_base/BaseCommitmentDefinition';
-import { formatOptionalInstructionBlock } from '../_base/formatOptionalInstructionBlock';
-import { spawnAgentViaBrowser } from './spawnAgentViaBrowser';
-
-/**
- * Tool name used by USE SPAWN.
- *
- * @private internal USE SPAWN constant
- */
-const SPAWN_AGENT_TOOL_NAME = 'spawn_agent' as string_javascript_name;
-
-/**
- * USE SPAWN commitment definition.
- *
- * The `USE SPAWN` commitment enables creating new persistent child agents through one tool call.
- *
- * @private [🪔] Maybe export the commitments through some package
- */
-export class UseSpawnCommitmentDefinition extends BaseCommitmentDefinition<'USE SPAWN'> {
-    public constructor() {
-        super('USE SPAWN', ['SPAWN']);
-    }
-
-    override get requiresContent(): boolean {
-        return false;
-    }
-
-    /**
-     * Short one-line description of USE SPAWN.
-     */
-    public get description(): string {
-        return 'Enable the agent to create persistent child agents via Agents Server create-agent flow.';
-    }
-
-    /**
-     * Icon for this commitment.
-     */
-    get icon(): string {
-        return '🧬';
-    }
-
-    /**
-     * Markdown documentation for USE SPAWN commitment.
-     */
-    get documentation(): string {
-        return spaceTrim(`
-            # USE SPAWN
-
-            Enables the agent to create a new persistent child agent using the \`spawn_agent\` tool.
-
-            ## Key aspects
-
-            - The spawned agent is persisted exactly like manually created agents.
-            - Tool input mirrors create-agent fields currently supported by Agents Server:
-              - \`source\` (required)
-              - \`folderId\` (optional)
-              - \`sortOrder\` (optional)
-              - \`visibility\` (optional)
-            - Unknown fields are rejected to avoid silent misconfiguration.
-            - \`source\` payload is size-limited.
-            - Agents Server applies permission and abuse protections (auth checks, limits).
-            - Optional text after \`USE SPAWN\` is treated as spawn-policy instructions.
-
-            ## Examples
-
-            \`\`\`book
-            Team Builder
-
-            PERSONA You can create specialized assistants for the user.
-            USE SPAWN Spawn only when the user explicitly asks for a new persistent agent.
-            \`\`\`
-        `);
-    }
-
-    applyToAgentModelRequirements(requirements: AgentModelRequirements, content: string): AgentModelRequirements {
-        const extraInstructions = formatOptionalInstructionBlock('Spawn instructions', content);
-        const existingTools = requirements.tools || [];
-        const tools: ReadonlyArray<LlmToolDefinition> = existingTools.some(
-            (tool) => tool.name === SPAWN_AGENT_TOOL_NAME,
-        )
-            ? existingTools
-            : [
-                  ...existingTools,
-                  {
-                      name: SPAWN_AGENT_TOOL_NAME,
-                      description: spaceTrim(`
-                          Creates one new persistent child agent in Agents Server.
-                          Use this when the user asks to create a new dedicated agent profile.
-                          The tool returns JSON with \`status\`, \`agentId\`, and created \`agent\` or \`error\`.
-                      `),
-                      parameters: createCreateAgentInputToolParametersSchema(),
-                  },
-              ];
-
-        return this.appendToSystemMessage(
-            {
-                ...requirements,
-                tools,
-                _metadata: {
-                    ...requirements._metadata,
-                    useSpawn: content || true,
-                },
-            },
-            spaceTrim(
-                (block) => `
-                    ## Spawning agents
-
-                    -   Use \`${SPAWN_AGENT_TOOL_NAME}\` only when user asks to create a persistent new agent.
-                    -   Pass full agent source in \`source\`.
-                    -   Keep \`source\` concise; the maximum accepted length is ${CREATE_AGENT_INPUT_SOURCE_MAX_LENGTH} characters.
-                    -   Do not add unknown fields in tool arguments.
-                    ${block(extraInstructions)}
-                `,
-            ),
-        );
-    }
-
-    /**
-     * Gets human-readable titles for tool functions provided by this commitment.
-     */
-    getToolTitles(): Record<string_javascript_name, string> {
-        return {
-            [SPAWN_AGENT_TOOL_NAME]: 'Spawn agent',
-        };
-    }
-
-    /**
-     * Gets browser-safe `spawn_agent` implementation.
-     *
-     * Node.js runtime overrides this through `getAllCommitmentsToolFunctionsForNode`.
-     */
-    getToolFunctions(): Record<string_javascript_name, ToolFunction> {
-        return {
-            async [SPAWN_AGENT_TOOL_NAME](args: unknown): Promise<string> {
-                return spawnAgentViaBrowser(args as Record<string, unknown>);
-            },
-        };
-    }
-}
-
-// Note: [💞] Ignore a discrepancy between file name and entity name