@promptbook/cli 0.114.0-3 → 0.114.0-5

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

package/src/commitments/USE_SPAWN/resolveSpawnAgentToolForNode.ts

@@ -1,42 +0,0 @@
-import { spaceTrim } from 'spacetrim';
-import { EnvironmentMismatchError } from '../../errors/EnvironmentMismatchError';
-import type { ToolFunction } from '../../scripting/javascript/JavascriptExecutionToolsOptions';
-
-/**
- * Resolves the server-side `spawn_agent` tool for Node.js runtimes.
- *
- * Uses lazy require so core package can load outside Agents Server.
- *
- * @private internal utility for USE SPAWN commitment
- */
-export function resolveSpawnAgentToolForNode(): ToolFunction {
-    try {
-        // eslint-disable-next-line @typescript-eslint/no-var-requires
-        const { spawn_agent } = require('../../../apps/agents-server/src/tools/spawn_agent');
-
-        if (typeof spawn_agent !== 'function') {
-            throw new Error('spawn_agent value is not a function but ' + typeof spawn_agent);
-        }
-
-        return spawn_agent 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) => `
-                        \`spawn_agent\` tool is not available in this environment.
-                        This commitment requires Agents Server runtime with agent persistence enabled.
-
-                        ${normalizedError.name}:
-                        ${block(normalizedError.message)}
-                    `,
-                ),
-            );
-        };
-    }
-}

package/src/commitments/USE_SPAWN/spawnAgentViaBrowser.ts

@@ -1,50 +0,0 @@
-/**
- * Browser-safe wrapper for spawning one persisted Agents Server agent.
- *
- * This function proxies requests to the Agents Server `/api/spawn-agent` endpoint.
- *
- * @param args Tool payload forwarded to server-side `spawn_agent` tool.
- * @param agentsServerUrl Optional explicit agents server base URL.
- * @returns JSON string with structured spawn result.
- *
- * @private internal utility for USE SPAWN commitment
- */
-export async function spawnAgentViaBrowser(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/spawn-agent', baseUrl);
-
-        const response = await fetch(apiUrl.toString(), {
-            method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-            },
-            body: JSON.stringify(args),
-        });
-
-        const payload = (await response.json().catch(() => ({}))) as {
-            success?: boolean;
-            result?: unknown;
-            error?: unknown;
-        };
-
-        if (payload.result !== undefined) {
-            return typeof payload.result === 'string' ? payload.result : JSON.stringify(payload.result);
-        }
-
-        if (!response.ok || payload.success === false) {
-            throw new Error(
-                `Failed to spawn agent: ${typeof payload.error === 'string' ? payload.error : response.statusText}`,
-            );
-        }
-        return JSON.stringify(payload);
-    } catch (error) {
-        const errorMessage = error instanceof Error ? error.message : String(error);
-        throw new Error(`Error spawning agent via browser: ${errorMessage}`);
-    }
-}

package/src/commitments/USE_TIME/USE_TIME.ts

@@ -1,177 +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';
-
-/**
- * USE TIME commitment definition
- *
- * The `USE TIME` commitment indicates that the agent should be able to determine the current date and time.
- *
- * Example usage in agent source:
- *
- * ```book
- * USE TIME
- * USE TIME Prefer the user's local timezone.
- * ```
- *
- * @private [🪔] Maybe export the commitments through some package
- */
-export class UseTimeCommitmentDefinition extends BaseCommitmentDefinition<'USE TIME'> {
-    public constructor() {
-        super('USE TIME', ['CURRENT TIME', 'TIME', 'DATE']);
-    }
-
-    override get requiresContent(): boolean {
-        return false;
-    }
-
-    /**
-     * Short one-line description of USE TIME.
-     */
-    public get description(): string {
-        return 'Enable the agent to determine the current date and time.';
-    }
-
-    /**
-     * Icon for this commitment.
-     */
-    get icon(): string {
-        return '🕒';
-    }
-
-    /**
-     * Markdown documentation for USE TIME commitment.
-     */
-    get documentation(): string {
-        return spaceTrim(`
-            # USE TIME
-
-            Enables the agent to determine the current date and time.
-
-            ## Key aspects
-
-            - This tool won't receive any input.
-            - It outputs the current date and time as an ISO 8601 string.
-            - Allows the agent to answer questions about the current time or date.
-            - The content following \`USE TIME\` is an arbitrary text that the agent should know (e.g. timezone preference).
-
-            ## Examples
-
-            \`\`\`book
-            Time-aware Assistant
-
-            PERSONA You are a helpful assistant who knows the current time.
-            USE TIME
-            \`\`\`
-
-            \`\`\`book
-            Travel Assistant
-
-            PERSONA You help travelers with planning.
-            USE TIME Prefer the user's local timezone.
-            \`\`\`
-        `);
-    }
-
-    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 'get_current_time' to tools if not already present
-        const updatedTools = existingTools.some((tool) => tool.name === 'get_current_time')
-            ? existingTools
-            : [
-                  ...existingTools,
-                  {
-                      name: 'get_current_time',
-                      description: 'Get the current date and time in ISO 8601 format.',
-                      parameters: {
-                          type: 'object',
-                          properties: {
-                              timezone: {
-                                  type: 'string',
-                                  description:
-                                      'Optional timezone name (e.g. "Europe/Prague", "UTC", "America/New_York").',
-                              },
-                          },
-                          required: [],
-                      },
-                  } as TODO_any, // <- TODO: !!!! Remove any
-                  // <- TODO: !!!! define the function in LLM tools
-              ];
-
-        return appendAggregatedUseCommitmentPlaceholder(
-            {
-                ...requirements,
-                tools: updatedTools,
-                _metadata: {
-                    ...requirements._metadata,
-                },
-            },
-            this.type,
-        );
-    }
-
-    /**
-     * Gets human-readable titles for tool functions provided by this commitment.
-     */
-    getToolTitles(): Record<string_javascript_name, string> {
-        return {
-            get_current_time: 'Get current time',
-        };
-    }
-
-    /**
-     * Gets the `get_current_time` tool function implementation.
-     */
-    getToolFunctions(): Record<string_javascript_name, ToolFunction> {
-        return {
-            async get_current_time(args: { timezone?: string }): Promise<string> {
-                console.log('!!!! [Tool] get_current_time called', { args });
-
-                const { timezone } = args;
-
-                if (!timezone) {
-                    return new Date().toISOString();
-                }
-
-                try {
-                    // Note: Returning ISO 8601 string but in the requested timezone
-                    const formatter = new Intl.DateTimeFormat('en-CA', {
-                        timeZone: timezone,
-                        year: 'numeric',
-                        month: '2-digit',
-                        day: '2-digit',
-                        hour: '2-digit',
-                        minute: '2-digit',
-                        second: '2-digit',
-                        hour12: false,
-                        timeZoneName: 'shortOffset',
-                    });
-
-                    const parts = formatter.formatToParts(new Date());
-                    const part = (type: string) => parts.find((p) => p.type === type)?.value;
-
-                    // en-CA format is YYYY-MM-DD
-                    const isoString = `${part('year')}-${part('month')}-${part('day')}T${part('hour')}:${part(
-                        'minute',
-                    )}:${part('second')}${part('timeZoneName')?.replace('GMT', '')}`;
-
-                    return isoString;
-                } catch (error) {
-                    // Fallback to UTC if timezone is invalid
-                    return new Date().toISOString();
-                }
-            },
-        };
-    }
-}
-
-// Note: [💞] Ignore a discrepancy between file name and entity name

package/src/commitments/USE_TIMEOUT/TimeoutToolNames.ts

@@ -1,13 +0,0 @@
-import type { string_javascript_name } from '../../types/string_person_fullname';
-
-/**
- * Tool names provided by the `USE TIMEOUT` commitment.
- *
- * @private internal USE TIMEOUT constant
- */
-export const TimeoutToolNames = {
-    set: 'set_timeout' as string_javascript_name,
-    cancel: 'cancel_timeout' as string_javascript_name,
-    list: 'list_timeouts' as string_javascript_name,
-    update: 'update_timeout' as string_javascript_name,
-} as const;